# HTTP API reference

> For the complete documentation index, see [llms.txt](https://crawlcoach.com/docs/llms.txt).

The CrawlCoach MCP endpoint over HTTP: how to authenticate, send a JSON-RPC request, and handle errors and rate limits.

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](https://crawlcoach.com/openapi.json) 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`:

```bash
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](https://crawlcoach.com/docs/mcp-tools).

## Errors

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

```json
{
  "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](https://crawlcoach.com/docs/plans-and-limits).