# SEOmatic app > The SEOmatic API and MCP server: SEO and AI-search answers about your own site, and the fixes your agents make on it. ## For agents - [A2A agent card](https://app.seomatic.ai/.well-known/agent-card.json): the A2A agent, its skills and how it signs in. - [OpenAPI](https://app.seomatic.ai/api/v1/openapi.json): REST API reference (OpenAPI 3.1), workspace API keys. - [MCP server](https://app.seomatic.ai/api/mcp): Streamable HTTP with OAuth 2.1; without sign-in, check_site gives a free first check of a website. - [MCP server card](https://app.seomatic.ai/api/mcp/server-card): the MCP server's name, version, transport and auth. - [pricing.json](https://app.seomatic.ai/pricing.json): machine-readable prices. - [auth.md](https://app.seomatic.ai/auth.md): how agents authenticate. - [Developer docs](https://seomatic.ai/developers): REST, MCP and webhooks guides. ## Pay as you go (prepaid credits) - No plan needed: buy prepaid credits in US dollars, from $20.00 to $100.00 per top-up. Prepaid credits can only be spent on SEOmatic services. They are not transferable and cannot be cashed out. They never expire, and unused credits are refunded on request. - Light market-data read (keyword, SERP, rank, competitor): $0.04 per unit; keyword suggestions per seed, competitor top pages per 200 rows. - Backlink read: $0.08 per unit; new and lost backlinks per 200 rows. - Question (POST /api/v1/ask): $0.15. Article: $9.00. AI-visibility scan: $19.00. Fix applied to your site: $1.90. - Search Console, site and stored reads are free. Free questions each month are spent first. - Failed calls are never charged: an error, a timeout or a refusal is given back. A valid answer that finds no data (for example a domain with no backlinks) is a successful call and is charged. - Exact price before a call: the free estimate_cost tool (pass the tool and its args). - Machine-readable prices: https://app.seomatic.ai/pricing.json (same as https://app.seomatic.ai/api/v1/pricing). - Too few credits answers HTTP 402 PREPAID_CREDITS_EMPTY with a top-up link and the API ways to pay (Checkout, Shared Payment Token, MPP). ## SEOmatic auth.md How AI agents authenticate to SEOmatic. An agent always acts for a SEOmatic user's workspace, with that user's consent. SEOmatic does not offer anonymous agent registration or ID-JAG identity assertions. There are two ways in: | You call | Credential | How you get it | | --- | --- | --- | | MCP server `https://app.seomatic.ai/api/mcp` | OAuth 2.1 access token, or a workspace API key | OAuth sign-in by the user, or a key the user creates | | REST API `https://app.seomatic.ai/api/v1` | Workspace API key only | The user creates it in the dashboard | Send either one as `Authorization: Bearer `. Without any credential, the MCP server's `check_site` tool gives a free first check of a website (rate limited per network). ### 1. Discover - MCP: an unauthenticated call to a protected tool returns `401` with `WWW-Authenticate: Bearer resource_metadata="https://app.seomatic.ai/.well-known/oauth-protected-resource/api/mcp"`. - Site-wide resource metadata: `https://app.seomatic.ai/.well-known/oauth-protected-resource`. - Authorization server (issuer `https://app.seomatic.ai`): `https://app.seomatic.ai/.well-known/oauth-authorization-server` (RFC 8414). - MCP server card: `https://app.seomatic.ai/api/mcp/server-card` (SEP-2127; also at `https://app.seomatic.ai/.well-known/mcp/server-card.json`). - REST API: OpenAPI 3.1 at `https://app.seomatic.ai/api/v1/openapi.json`. - API catalog: `https://app.seomatic.ai/.well-known/api-catalog` (RFC 9727). ### 2. OAuth 2.1 (MCP clients) - Authorization code grant with PKCE (`S256` only). Authorize: `https://app.seomatic.ai/api/oauth/authorize`. Token: `https://app.seomatic.ai/api/oauth/token`. - Client registration, pick one: - Dynamic Client Registration (RFC 7591): `POST https://app.seomatic.ai/api/oauth/register` with JSON client metadata. - Client ID Metadata Documents: use the HTTPS URL of your client metadata document as `client_id`. - Public clients use token endpoint auth method `none`. - Scopes: `read:gsc` (Search Console data), `chat:ask` (questions and insights), `agents:act` (stage site changes; needs a paid plan). - The user signs in in a browser and approves access. Refresh tokens are issued (`refresh_token` grant). - Revoke: `POST https://app.seomatic.ai/api/oauth/revoke` (RFC 7009). - The device authorization grant (RFC 8628) exists but is limited to the SEOmatic CLI (`npx seomatic`); other clients get `unauthorized_client`. An OAuth access token works only on the MCP server. Sent to the REST API it is rejected with `401 INVALID_TOKEN`. ### 3. Workspace API keys (REST API and MCP) - A workspace admin creates the key in the dashboard: Settings, AI Agents, API Keys (https://app.seomatic.ai). An agent cannot create one on its own; ask the user to create it and give it to you. - Keys look like `smk_live_...` (or `smk_test_...`, which behave the same) and are shown once. - Keys carry the same scopes. `read:gsc` and `chat:ask` are free; `agents:act` is paid. - The user revokes a key in the same place. ### 4. Limits and errors - Free workspaces get 5 questions a month, shared by the app, the MCP server and the REST API. When they run out, calls return `402 FREE_QUOTA_EXCEEDED`. - A key without a needed scope gets `MISSING_SCOPE`, with an upgrade link. - Tools that change the site over the REST API need the Infrastructure plan. - Changes an agent stages follow the workspace's autonomy mode: in Approval mode each one waits for a person to approve it. Docs: https://seomatic.ai/developers (MCP: https://seomatic.ai/developers/mcp, REST: https://seomatic.ai/developers/rest-api).