# Set up the SEOFix MCP server by hand

> Manual MCP setup for Claude Code, Codex, Cursor and other clients - endpoint, Authorization bearer header, transport and connection troubleshooting.

Source: https://seofix.ai/help/mcp-server · Category: AI agents & MCP · Updated: 2026-10-08

The SEOFix MCP server is a remote Streamable HTTP server at `https://mcp.seofix.ai/mcp`. Add it to your agent with your API key in an `Authorization: Bearer sk_...` header. The quickest way is [`npx seofix connect`](https://seofix.ai/help/connect-your-agent.md); this page covers doing it by hand.

## Before you start

You need an API key. In the app: Settings → Agent & MCP → **Create API key**. Copy it from the dialog: it is shown only once. The key acts for the team you were viewing when you created it. See [API keys](https://seofix.ai/help/api-keys.md).

In the examples below, replace `sk_...` with your key.

## Claude Code

Run in your project's terminal:

```bash
claude mcp add --transport http seofix https://mcp.seofix.ai/mcp \
  --header "Authorization: Bearer sk_..."
```

Add `--scope user` to use it in every project, not only this one. Check it with `claude mcp get seofix`.

## Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.seofix]
url = "https://mcp.seofix.ai/mcp"
http_headers = { "Authorization" = "Bearer sk_..." }
```

To keep the key out of the file, use `bearer_token_env_var = "SEOFIX_API_KEY"` instead of `http_headers`, and set `SEOFIX_API_KEY` in the environment Codex runs in.

## Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "seofix": {
      "url": "https://mcp.seofix.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_..."
      }
    }
  }
}
```

This file holds your key. Keep it out of version control, for example by adding `/.cursor/mcp.json` to `.git/info/exclude` or `.gitignore`.

## Other MCP clients

Any client that supports remote HTTP servers with custom headers works. The generic shape is:

```json
{
  "mcpServers": {
    "seofix": {
      "type": "http",
      "url": "https://mcp.seofix.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_..."
      }
    }
  }
}
```

Key names differ between clients; check your client's documentation. If your client only supports local stdio servers, put an HTTP-to-stdio bridge in front of the URL. The server itself only speaks Streamable HTTP.

## How the server works

| Property | Value |
| --- | --- |
| Endpoint | `https://mcp.seofix.ai/mcp` |
| Transport | Streamable HTTP, stateless: no sessions, no server-initiated notifications |
| Methods | `POST /mcp` only. `GET` and `DELETE /mcp` answer 405 `Method not allowed.`; any other path answers 404. |
| Auth | `Authorization: Bearer sk_...` on every request. The `Bearer ` prefix is optional. |
| Tools | 33, listed in the [MCP tools reference](https://seofix.ai/help/mcp-tools-reference.md) |

The server holds no credentials. It reads the bearer token from each request and passes it to the SEOFix REST API (`https://api.seofix.ai/v1`). Every tool call is therefore subject to the same permissions, credit costs and rate limits as the API: 60 requests per minute per key, plus per-endpoint limits. See [Errors and rate limits](https://seofix.ai/help/errors-and-rate-limits.md).

## Tool results and errors

A successful tool returns one text item, usually compact JSON. `get_fix_prompt` returns markdown.

A failed tool returns a text item with `isError: true` in the form `code: message`, for example:

```text
site_not_verified: Rechecks need a verified site. Verify ownership first: see GET /v1/sites/{id}/verification.
```

`budget_exhausted` errors also carry ` (resets_at: <ISO time>)`. The codes are the API's error codes; see [Errors and rate limits](https://seofix.ai/help/errors-and-rate-limits.md).

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| `unauthenticated: No API key provided.` | The client sent no `Authorization` header. Check the header name and that your client supports custom headers for HTTP servers. |
| `unauthenticated: Valid API key required.` | The key is wrong, was revoked, or was replaced by a rotation. Create a new key or run `npx seofix connect`. |
| `team_access_revoked: ...` | You are no longer a member of the team the key acts for. Get a new key for a team you belong to. |
| `rate_limited: ...` | More than 60 calls per minute with this key, or a per-endpoint limit. Wait and retry. |
| `network_error: Could not reach the audit API` | The MCP server could not reach the API. Retry shortly; if it persists, email hello@seofix.ai. |
| The client cannot connect or lists no tools | Check the URL is exactly `https://mcp.seofix.ai/mcp`, that the transport is HTTP (not SSE or stdio), and restart the agent after changing its config. |
| The agent still uses an old key | Agents read their MCP config at start. Restart the agent after rotating or reconnecting. |

To test your key without MCP:

```bash
curl -s https://api.seofix.ai/v1/ping -H "Authorization: Bearer $SEOFIX_API_KEY"
```

A valid key answers `{"user_id": ...}`.

## Related

- [Connect your agent with npx seofix connect](https://seofix.ai/help/connect-your-agent.md)
- [MCP tools reference](https://seofix.ai/help/mcp-tools-reference.md)
- [Agent playbook](https://seofix.ai/help/agent-playbook.md)
- [API keys](https://seofix.ai/help/api-keys.md)