HTTP API reference

CrawlCoach's API is its MCP server at https://crawlcoach.com/mcp. It speaks JSON-RPC 2.0 over the MCP Streamable HTTP transport and answers with JSON. Most MCP clients handle this for you. Use this page if you build your own client.

The OpenAPI description covers the same endpoints.

Endpoints

Method	Path	Description
POST	/mcp	Sends one JSON-RPC message. Requires a bearer token.
GET	/.well-known/oauth-protected-resource/mcp	Returns the OAuth protected resource metadata. No token.
GET	/docs/llms.txt	Returns the docs index for AI agents. No token.
GET	/openapi.json	Returns the OpenAPI description. No token.

Authentication

Every /mcp request needs an OAuth 2.0 access token in the Authorization header. CrawlCoach doesn't issue API keys.

To get a token, your client follows the MCP authorization flow:

1. Send a request to /mcp without a token. The 401 Unauthorized response has a WWW-Authenticate header that points to https://crawlcoach.com/.well-known/oauth-protected-resource/mcp.
2. Read the metadata. It names the authorization server, https://clerk.crawlcoach.com, and the supported scopes.
3. Run the OAuth authorization code flow with PKCE against that server. Use a client ID metadata document: an HTTPS URL as your client_id. The user signs in to CrawlCoach and clicks Allow.
4. Send the access token on every request.

The scopes are crawlcoach:read and crawlcoach:write. recheck_pages needs crawlcoach:write. The other tools need crawlcoach:read.

The token must belong to a Google account that already has a CrawlCoach account.

Send a request

The following request calls list_sites:

curl https://crawlcoach.com/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_sites","arguments":{}}}'

Replace ACCESS_TOKEN with the OAuth access token for the user.

Send one JSON-RPC message per request. Batches aren't accepted. A request body can be up to 512 KB.

The MCP methods are initialize, tools/list, tools/call, prompts/list, and prompts/get. For each tool's arguments and results, see MCP tools reference.

Errors

HTTP errors have a JSON body with error, a message, and code:

{
  "error": "Connect your CrawlCoach account.",
  "code": "TOKEN_REQUIRED"
}

Status	Code	Meaning
400 Bad Request		The body isn't one JSON-RPC message.
401 Unauthorized	TOKEN_REQUIRED	The request has no token. Sign in.
401 Unauthorized	INVALID_TOKEN	The token is expired, revoked, or not for CrawlCoach. Sign in again.
403 Forbidden	ACCOUNT_REQUIRED	The Google account has no CrawlCoach account. Create one first.
403 Forbidden	INSUFFICIENT_SCOPE	The token lacks the scope this tool needs. Sign in again and allow it.
413 Content Too Large		The body is over 512 KB.
429 Too Many Requests	RATE_LIMITED	Too many requests. Wait for the Retry-After seconds and try again.
503 Service Unavailable	AUTHENTICATION_UNAVAILABLE	CrawlCoach can't check the token right now. Try again later.

A 401 or an INSUFFICIENT_SCOPE response has a WWW-Authenticate header that tells the client how to sign in again.

A tool that runs but can't answer returns a normal JSON-RPC result with isError: true, not an HTTP error. For example, recheck_pages returns one when the site has no rechecks left today.

Rate limits

CrawlCoach limits requests for each token and for each account. When you reach a limit, the response is 429 Too Many Requests with Retry-After: 60. Wait a minute, and then try again.

Tools have their own limits, such as 200 rechecks for each Search Console property each day. For the full list, see Plans and limits.