MCP Documentation

The Model Context Protocol (MCP) allows AI assistants like Claude, GPT, and Cursor to interact directly with your Better Search Console data. Your assistant can list websites, check indexation status, analyze prompts, manage sitemaps, and much more — all through a standardized tool-calling interface.

Endpoint

The MCP server is available at:

https://<your-host>/_mcp

Authentication

Three methods are supported (in priority order):

Method	Example
`X-API-TOKEN` header	`X-API-TOKEN: your_token_here`
`Authorization: Bearer` header	`Authorization: Bearer your_token_here`
`?token=` query parameter	`/_mcp?token=your_token_here`

Find your API token in Settings. It is a 64-character hex string.

OAuth Flow

For clients that support OAuth, the MCP endpoint also accepts standard OAuth 2.0 Bearer tokens obtained via the Google OAuth flow. The access token returned after the user authorizes is stored on the user record and can be used as a Bearer token.

Setup Instructions

Claude.ai (Web)

{
  "mcpServers": {
    "better-search-console": {
      "url": "https://<your-host>/_mcp?token=<YOUR_API_TOKEN>"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "better-search-console": {
      "url": "https://<your-host>/_mcp",
      "headers": {
        "X-API-TOKEN": "<YOUR_API_TOKEN>"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "better-search-console": {
      "url": "https://<your-host>/_mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_TOKEN>"
      }
    }
  }
}

Rate Limits

Tier	Requests/min	Requests/day
Free	10	50
Starter	100	200
Pro	200	500
Master	Unlimited	Unlimited

Tool Reference (48 tools)

Usage Examples

List your websites:

Tool: list-websites
Arguments: {}

Check indexation for a URL:

Tool: check-url-indexation
Arguments: { "website_id": 1, "url": "https://example.com/page" }

Submit URLs for indexing:

Tool: submit-urls-for-indexing
Arguments: { "website_id": 1, "url_ids": [10, 11, 12] }

Troubleshooting

Issue	Solution
401 Unauthorized	Check your API token is correct and included in the request.
429 Too Many Requests	You have exceeded your rate limit. Wait or upgrade your plan.
Tool not found	Verify the tool name matches the reference above exactly.
Connection refused	Ensure the host URL is correct and accessible from your network.
Invalid parameters	Check required parameters match the schema. IDs must be numbers.