MCP server

Live

A remote Model Context Protocol server that plugs SERP Agent directly into Claude Code, Claude.ai, Cursor, VS Code, and any other MCP-capable agent. It is a thin layer over the /v1 REST API — same accounts, same API keys (Authorization: Bearer sk_…), same sandbox trial, identical rate limits and budgets.

Endpoint

URL: https://serp-agent.com/mcp
Transport: Streamable HTTP (stateless — no session required; JSON-RPC over POST).
Auth: Authorization: Bearer sk_… — the same keys as the REST API. No key yet? Sign up in one call: POST /v1/accounts {"email":"you@example.com"} returns a free sandbox key instantly (agent quickstart).

Connect

Claude Code

claude mcp add --transport http serpagent https://serp-agent.com/mcp \
  --header "Authorization: Bearer sk_..."

Claude.ai / Claude Desktop (custom connector)

Settings → Connectors → Add custom connector → URL https://serp-agent.com/mcp. No key needed: Claude discovers our OAuth 2.1 authorization server automatically, opens a browser consent page, and you approve with your dashboard login (or by pasting an API key). See OAuth 2.1 below.

Cursor

Add to ~/.cursor/mcp.json (or project .cursor/mcp.json):

{
  "mcpServers": {
    "serpagent": {
      "url": "https://serp-agent.com/mcp",
      "headers": { "Authorization": "Bearer sk_..." }
    }
  }
}

VS Code (GitHub Copilot agent mode)

Add to .vscode/mcp.json:

{
  "servers": {
    "serpagent": {
      "type": "http",
      "url": "https://serp-agent.com/mcp",
      "headers": { "Authorization": "Bearer sk_..." }
    }
  }
}

Stdio-only clients

Clients that only speak stdio can bridge to the remote server with the serpagent-mcp npm package (a thin mcp-remote wrapper), or mcp-remote directly:

npx -y serpagent-mcp            # reads SERPAGENT_API_KEY from the environment
# or, without the wrapper:
npx -y mcp-remote https://serp-agent.com/mcp \
  --header "Authorization: Bearer sk_..."

Tools

Tool names are snake_case with LLM-oriented descriptions. Long-running jobs (audits, articles) return a job id immediately with matching get_* polling tools — poll with backoff.

Tool	Purpose	Status
create_project	Register a site/domain to work on. Returns project_id.	live
list_projects	List existing projects with status and access.	live
get_project	Fetch one project incl. audit/article counts.	live
run_technical_audit	Start a technical SEO audit (202 + audit_id; poll get_audit_report).	live
get_audit_report	Audit status + summarized report (issues, priorities, categories) — not a 200-page dump.	live
generate_article	Generate an SEO article (202 + article_id; poll get_article).	live
get_article	Article status + full content/meta once ready.	live
get_account_status	Mode, usage, remaining limits — lets agents self-manage spend.	live
list_plans	Public machine-readable pricing/limits catalog.	live

Planned tools

These ship as their /v1 endpoints land — the MCP layer mirrors REST 1:1, so nothing is stubbed before the API exists.

Tool	Purpose	Status
generate_seo_strategy	Generate keyword/content strategy for a project given goals and niche.	planned
publish_content	Publish or schedule content to the connected CMS.	planned
get_rankings	Current tracked keyword positions + deltas.	planned
get_ai_visibility	Brand/domain visibility across 8 AI platforms, with trend.	planned
get_backlinks	Backlink profile summary + recently lost links.	planned
run_local_seo_check	Local SEO status and actions for a location.	planned

OAuth 2.1

The MCP server implements the MCP authorization spec (OAuth 2.1, authorization-code + PKCE S256, dynamic client registration) — the requirement for the Claude.ai connectors directory. Spec-compliant clients handle all of this automatically: an unauthenticated request to /mcp returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata, the client registers itself, opens the consent page, and exchanges the code for a 30-day access token. Manual Bearer sk_… headers keep working unchanged.

Discovery: /.well-known/oauth-protected-resource/mcp (RFC 9728) and /.well-known/oauth-authorization-server (RFC 8414).
Endpoints: POST /oauth/register (RFC 7591, public clients), GET /oauth/authorize (consent page — approve with your dashboard session or by pasting an sk_ key), POST /oauth/token (PKCE S256 required).
Tokens are tied to one of your API keys and inherit its limits; revoking the key (or the token) cuts access immediately. No refresh tokens — after 30 days the client re-runs the browser flow.

Notes

Errors from the API surface as tool errors with the same uniform {"error":{code,message,doc_url}} body as REST — your agent can read the message and self-correct (e.g. sandbox budget exhausted → surface the upgrade link to a human).
Prefer plain REST? Everything the tools do is documented in /openapi.json and the agent quickstart.