# MCP server

> Hosted [Model Context Protocol](https://modelcontextprotocol.io) endpoint for Claude Code, Cursor, or any MCP client — readiness checks, GEO measurement, and findings without leaving your editor.

Server URL: `https://crawrix.ai/api/mcp`

## Connect

1. **Add the server.** Point any spec-compliant MCP client at `https://crawrix.ai/api/mcp`. The client discovers OAuth, opens a browser, and you click Authorize. Max or Ultra Max required.
2. **Call a tool.** Start with `check_site_readiness` on a public URL, or load the `improve_ai_visibility` prompt for a full fix loop.
3. **Revoke later.** Connected clients appear under [Settings → MCP clients](https://crawrix.ai/app/settings). Revoking drops the access and refresh tokens together.

Claude Code:

```bash
claude mcp add --transport http crawrix https://crawrix.ai/api/mcp
```

Cursor — `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "crawrix": {
      "url": "https://crawrix.ai/api/mcp"
    }
  }
}
```

> **Headless / CI.** OAuth needs a browser. For scripts, mint a CLI token with `crawrix login --hosted` and send it as `Authorization: Bearer`. That path is unchanged.

Raw Streamable HTTP (CLI token):

```http
POST https://crawrix.ai/api/mcp
Authorization: Bearer <token>
Accept: application/json, text/event-stream
Content-Type: application/json
```

## What it exposes

Only outcomes we uniquely own. Your agent already reads your repository better than we could, so the server has no repo-browsing tools — and it never opens a pull request on a bare tool call.

- `check_site_readiness` — Deterministic AI-readiness crawl of any public site: AI-crawler access in robots.txt, llms.txt, Organization/LocalBusiness JSON-LD, sameAs, sitemap, answer-ready structure, name consistency. Returns a 0–100 score with a fix for every failure.
- `list_businesses` / `save_business` — Businesses on your account. Idempotent by website address — saving the same site twice updates rather than duplicates.
- `start_geo_run` / `get_geo_run` (metered) — Measure whether AI platforms actually know, cite, and recommend a business. Returns a run id immediately; poll for status.
- `get_geo_report` — The scored report: overall score, pillar scores, every readiness check with evidence, probe evidence, and score history.
- `list_audits` / `list_findings` — Read what has already been found on your account, filtered by kind, severity, status, or category.
- `record_findings` — Persist issues your agent found into your crawrix account, where they join the audit → pull-request loop and close automatically when the PR merges.

## Prompts

- `improve_ai_visibility` — Check a site, triage the failures, fix them in the repo you are sitting in, re-check to prove the score moved.
- `record_seo_audit` — Audit the current repository with your agent's own file access, then persist results to crawrix so they show on the dashboard and can become pull requests.

## Limits and safety

- A token authenticates one account. Every read and write is scoped to it — there is no way for a request body to name a different tenant.
- Readiness checks are capped at 30/hour and finding ingests at 20/hour per account. Measurement runs share the same daily cap as the web app.
- Any URL you hand the server is validated before we fetch it, on every redirect hop — private, loopback, and cloud-metadata addresses are refused.
- Nothing on this server writes to GitHub. Opening a pull request still requires explicit approval in the app.
- Revoke a client or CLI token any time in Settings; it stops working on the next request.

> **Scoring parity.** Readiness and GEO scores match the web app and CLI because the tools call the same core — see [Methodology](https://crawrix.ai/docs/methodology).
