# Nodpick AI readiness: API and MCP server for agents

> Free, deterministic audit of how well a public website can be found and cited by AI assistants (ChatGPT, Claude, Perplexity, Gemini). No account, no API key, no LLM calls: fixed rules over up to five fetched URLs. Use it when a user asks to make a site visible to AI, about GEO or AEO, or why an assistant does not mention their site.

## What it does

`audit_ai_readiness` fetches the page (once like a browser, once with an AI search bot user agent), `/robots.txt`, the sitemap and `/llms.txt`, and returns:

- a score from 0 to 100 with open weights,
- seven weighted checks plus one informational check (training crawlers, 0 points), each with status (pass, warn, fail, info), points, an evidence label (A, B or C), a one-line finding and a fix,
- up to five top fixes ranked by points gained,
- a next step: a link to the free check that measures whether the assistants actually name the brand.

Single-page apps (Lovable, Bolt, Vite) are detected: AI crawlers read raw HTML and do not run JavaScript, so a client-rendered page looks empty to them. The audit says so and offers prerender options.

Responses never contain raw text of the audited page, only our own findings, so a hostile page cannot inject instructions into your agent.

## MCP server

Endpoint: `https://nodpick.com/mcp` (Streamable HTTP, stateless, no authentication, read-only).

| Tool | Input | Returns |
|---|---|---|
| `audit_ai_readiness` | `url`, optional `framework` | Audit AI readiness of a website |
| `check_ai_crawlers` | `url` | Check which AI crawlers can reach a site |
| `check_llms_txt` | `url` | Check a site's llms.txt |
| `get_fix_snippet` | `check`, optional `framework` | Get a copy-paste fix |
| `get_free_visibility_check_link` | `domain`, optional `country`, `language` | Get the free AI visibility check link |

All tools are annotated `readOnlyHint: true`. The tools that fetch pages also set `openWorldHint: true`. Every result has structured content plus a short Markdown summary.

### Install

Claude Code:

```bash
claude mcp add --transport http ai-readiness https://nodpick.com/mcp
```

Cursor, `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "ai-readiness": { "url": "https://nodpick.com/mcp" }
  }
}
```

VS Code, `.vscode/mcp.json`:

```json
{
  "servers": {
    "ai-readiness": { "type": "http", "url": "https://nodpick.com/mcp" }
  }
}
```

Windsurf, `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "ai-readiness": { "serverUrl": "https://nodpick.com/mcp" }
  }
}
```

Claude Desktop and claude.ai: add a custom connector with the URL `https://nodpick.com/mcp`.

Any other client: use the URL above as a Streamable HTTP server. Clients that only speak stdio can bridge with `npx -y mcp-remote https://nodpick.com/mcp`.

## REST API

OpenAPI 3.1: `https://nodpick.com/api/v1/openapi.json`. CORS is open for GET.

```bash
curl "https://nodpick.com/api/v1/ai-readiness?url=https://example.com&framework=nextjs"
curl "https://nodpick.com/api/v1/fix-snippet?check=crawler_access&framework=nextjs"
```

- `GET /api/v1/ai-readiness?url=&framework=` returns the audit as JSON.
- `GET /api/v1/fix-snippet?check=&framework=` returns a copy-paste fix (no fetching).
- Errors are JSON: `{ "error": { "code": "invalid_url", "message": "..." } }` with status 400, 422, 429 or 503.

`framework` is one of: `nextjs`, `astro`, `wordpress`, `static`, `spa`, `nginx`, `apache`, `other`. `check` is one of: `crawler_access`, `training_crawlers`, `raw_html_content`, `indexability`, `metadata`, `structured_data`, `freshness`, `agent_extras`.

## Checks and weights

| Check | Points |
|---|---:|
| `crawler_access` | 25 |
| `raw_html_content` | 25 |
| `indexability` | 20 |
| `metadata` | 10 |
| `structured_data` | 10 |
| `freshness` | 5 |
| `agent_extras` | 5 |

`training_crawlers` is informational and worth 0 points.

## Evidence policy

Every check carries a label and a source so you can judge how much to trust it:

- **A**: documented by the vendors themselves (crawler tokens and purposes, indexing basics).
- **B**: supported by a study (content must be in the raw HTML).
- **C**: unproven. JSON-LD, llms.txt, Markdown access, freshness dates and metadata hygiene have no demonstrated effect on AI citations, so they carry small weights. The report says so instead of presenting them as proven.

Blocking AI training crawlers (GPTBot, ClaudeBot, Google-Extended, ...) is a legitimate choice and never costs points. Training bots are separate from the search bots that decide whether you appear in an assistant's answers.

The user-agent test only changes the HTTP header from our IP (the official bot token stays in it, followed by an identifier with a link to these docs). Real bots are also verified by IP, so a block we see may not apply to them. The report words this as a warning, not a verdict.

## Your own action plan (personal API key)

The tools above are public and need no account. If you track a brand in the Nodpick portal, a coding agent can fetch its ranked action plan with a personal, read-only API key. Create the key under Settings, "API & coding agents" (every paid plan; keys are shown once and can be revoked any time).

- REST: `GET https://nodpick.com/api/v1/projects` lists your brands; `GET https://nodpick.com/api/v1/projects/{id}/action-plan` (optional `framework` and `lang=en|de`) returns the plan. Send `Authorization: Bearer npk_...`. Projects of other accounts answer 404.
- MCP: connect `https://nodpick.com/mcp` with the same header, for example in Claude Code `claude mcp add --transport http nodpick https://nodpick.com/mcp --header "Authorization: Bearer <key>"`. With a valid key two more tools appear, `list_projects` and `get_action_plan`; without a key the server offers the public tools only.
- Per item you get the measured evidence with its grade, steps, a fix snippet where the item is a code change, acceptance criteria and a ready prompt. In the portal, every action also has a "Fix with your coding agent" button that copies the same prompt.
- Keys are read-only and limited to 60 requests per minute each. A key stops working when it is revoked, when its owner leaves the team, or when the account is on the free plan (403). Never commit a key to a repository.

Nodpick supplies the task and the data; your own agent makes the change in your repository.

## Limits

- Up to 5 fetches per audit, 5 seconds and 1 MB each, http and https only, ports 80 and 443, at most 3 redirects. Private, loopback and link-local addresses are refused, also after redirects.
- Results are cached for 24 hours per URL (10 minutes when part of the audit could not be verified).
- Timeouts, server errors and rate limits on the audited site are never counted against it: those parts are marked as not verified, removed from the maximum, and the score is scaled to 100 (`partial: true`). Batches of more than 5 JSON-RPC requests are refused on `/mcp`.
- If the page redirects to another domain, only that host is reported (`redirectedOffsite: true`), not the full URL.
- 20 uncached audits per hour per client, 200 calls of any kind per hour per client, 10 per target site per hour, plus a global hourly cap. Cached results are free.
- The API and the MCP server are free offers under our [Terms of service](https://nodpick.com/legal/terms) (section 8): no warranty of availability or results, fair use, may change. Privacy: https://nodpick.com/legal/privacy.
- Rate limits use a salted hash of the client IP address, deleted after two days. Usage counters are per day, channel and tool, without IP addresses or URLs.

## Next step

https://nodpick.com/#check: the free check asks ChatGPT, Perplexity, Gemini and Claude buyer questions and shows whether they name the brand. The audit tools return a link with `ref=api` or `ref=mcp`.