Connect SEOReport to Claude Code: MCP setup for SEO audits

What you need

You need an active SEOReport plan and an API key. Create the key at https://seoreport.dev/dashboard/api-keys. API keys require an active plan. [3][4][1]

SEOReport shows the key once. Store it in a secret store or an environment variable, not in a prompt, a project file or your shell history. [4]

The server speaks streamable HTTP at https://seoreport.dev/mcp. It expects the key on every request as an Authorization: Bearer <api-key> header, the same key you use for the REST API. [3][4][1]

You also need Claude Code installed. The commands below come from Claude Code's MCP documentation. [5]

Add the server

Set SEOREPORT_API_KEY in your shell profile, then add the server to .mcp.json in your project. The file holds ${SEOREPORT_API_KEY}, not the key, and Claude Code expands it when it connects. [5]

We do not show the claude mcp add --header form. It puts the key on a command line, where other local users can read it while the command runs, and Claude Code stores what it is given in ~/.claude.json. [5]

export SEOREPORT_API_KEY="sr__live_your_api_key"

{
  "mcpServers": {
    "seoreport": {
      "type": "http",
      "url": "https://seoreport.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SEOREPORT_API_KEY}"
      }
    }
  }
}

Confirm it works

Run claude mcp list. It shows a health status next to each server, such as Connected or Failed to connect. Inside a session, run /mcp to check the server and its tools. [5]

You should see 9 tools whose names start with seoreport_: seoreport_create_report, seoreport_get_report_status, seoreport_get_report, seoreport_list_reports, seoreport_get_report_download, seoreport_get_account, seoreport_list_plans, seoreport_start_checkout and seoreport_submit_feedback. [3]

Then try a first prompt: "Audit https://example.com and list the three highest-severity findings." The agent can start the audit with seoreport_create_report and read the findings with seoreport_get_report. A report takes up to about 30 seconds. [4][3]

A new site uses one credit from your plan. Running a site you already have a report for again does not use a credit. [1][2]

Keep the key out of version control

A local-scope or user-scope server lives in ~/.claude.json in your home folder, outside the repository. A project-scope server lives in .mcp.json, which Claude Code expects you to check in. [5]

So in .mcp.json, reference an environment variable instead of the key. Claude Code expands ${VAR} and ${VAR:-default} in the url and headers of HTTP servers. [5]

Use a variable name of your own, such as SEOREPORT_API_KEY. Claude Code reads its own and your cloud provider's credential variables, such as ANTHROPIC_API_KEY, as empty in a remote server's headers. A name outside that set expands as written. [5]

Claude Code asks for approval before it uses project-scoped servers from .mcp.json in interactive sessions. [5]

Troubleshooting

Authentication error or HTTP 401: SEOReport lists and calls tools only for a valid key. Check that the header value is Bearer, one space, then the key. If the key may be wrong or exposed, revoke it and create a new one in the dashboard. [3][4]

If SEOREPORT_API_KEY is not set, Claude Code still loads the config, reports a missing-variable warning in claude mcp list and sends the unexpanded ${SEOREPORT_API_KEY} text. [5]

If a remote server's headers reference a covered credential variable you have set, Claude Code names it in a debug log. Run claude --debug-file /tmp/claude-debug.log and search the file for "never expanded toward a remote server". [5]

Plan or credit error: if seoreport_create_report says an active plan is required or the month's credits are used, the key works but the account cannot start a report. Ask the agent to call seoreport_get_account to see the plan and the credits left. [4]

To subscribe from the agent, it can call seoreport_list_plans and then seoreport_start_checkout. Checkout returns a browser link: an agent can start it, and only a person can pay. Credits reset on the first day of each month (UTC). [4][1]

Tools not listed: open /mcp and reconnect the server. After five failed reconnection attempts, Claude Code marks a server as failed, and you can retry it manually from /mcp. [5]