---
title: Quickstart — Agent Ready REST API and MCP server
description: Run your first Agent Ready scan in under 60 seconds. Get an API key, POST to /api/v1/scans, poll the result, or wire the MCP server into Claude Desktop / Cursor. Worked examples in curl, Node, Python, and MCP JSON.
last_updated: 2026-05-28
canonical_url: https://agent-ready.dev/quickstart
---

# Agent Ready quickstart — REST API and MCP server

> Run your first Agent Ready scan in under 60 seconds. Get an API key, POST to `/api/v1/scans`, poll the result, or wire the MCP server into Claude Desktop / Cursor. Worked examples in curl, Node, Python, and MCP JSON. MCP server: https://agent-ready.dev/api/v1/mcp.

## What is Agent Ready?

Agent Ready scores any website against the Vercel Agent Readability Spec, llmstxt.org, MCP server-card discovery (SEP-1649), A2A agent cards, agents.json, agent-permissions.json, UCP, x402, and NLWeb conventions. The same checks are exposed as a REST API and an MCP server so agents can score sites and search the Agent Ready glossary without scraping HTML.

## Step-by-step

### Step 1 — Get an Agent Ready API key

Sign in at https://agent-ready.dev/sign-in and open /dashboard/api-keys. Click Create key, name it after the workload, and copy the Bearer token. Pro plan required. Free-tier accounts can sign up but cannot mint a key.

### Step 2 — Run your first scan

POST to https://agent-ready.dev/api/v1/scans with Authorization: Bearer <key> and a JSON body containing the URL to scan. The response returns immediately with a scan id and status: queued. Scans take 5-30 seconds depending on the number of pages crawled.

### Step 3 — Poll for results

GET https://agent-ready.dev/api/v1/scans/{id} with the same Bearer token. Poll every 2-3 seconds until status is complete. The completed response includes the agent-readiness score, the per-check breakdown, and a shareable URL.

### Step 4 — Integrate via MCP

MCP server: https://agent-ready.dev/api/v1/mcp. Add a server entry to your MCP client config (Claude Desktop, Cursor, Cline, Continue, Goose) using the streamable-http transport with the same Bearer token. The server exposes scan_site, get_scan, and ask tools — your agent can run scans and search the Agent Ready docs without a custom client.

## Code examples

### curl

```bash
# 1. Start a scan
curl -X POST https://agent-ready.dev/api/v1/scans \
  -H "Authorization: Bearer $AGENT_READY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# Response:
# {"id":"scan_01HXYZ...","status":"queued","shareUrl":null}

# 2. Poll for results
curl https://agent-ready.dev/api/v1/scans/scan_01HXYZ... \
  -H "Authorization: Bearer $AGENT_READY_KEY"

# When status flips to "complete":
# {"id":"scan_01HXYZ...","status":"complete","score":87,"rating":"good","shareUrl":"https://agent-ready.dev/scan/..."}
```

### Node (TypeScript)

```typescript
const KEY = process.env.AGENT_READY_KEY!;
const base = "https://agent-ready.dev/api/v1";

const start = await fetch(`${base}/scans`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
}).then((r) => r.json());

let result = start;
while (result.status !== "complete") {
  await new Promise((r) => setTimeout(r, 2_000));
  result = await fetch(`${base}/scans/${start.id}`, {
    headers: { Authorization: `Bearer ${KEY}` },
  }).then((r) => r.json());
}

console.log("Score:", result.score, result.shareUrl);
```

### Python

```python
import os, time, requests

KEY = os.environ["AGENT_READY_KEY"]
base = "https://agent-ready.dev/api/v1"
h = {"Authorization": f"Bearer {KEY}"}

start = requests.post(
    f"{base}/scans",
    headers={**h, "Content-Type": "application/json"},
    json={"url": "https://example.com"},
).json()

result = start
while result["status"] != "complete":
    time.sleep(2)
    result = requests.get(f"{base}/scans/{start['id']}", headers=h).json()

print("Score:", result["score"], result["shareUrl"])
```

### MCP client config

```json
{
  "mcpServers": {
    "agent-ready": {
      "transport": "streamable-http",
      "url": "https://agent-ready.dev/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${AGENT_READY_KEY}"
      }
    }
  }
}
```

The MCP server exposes three tools: `scan_site` (start a scan), `get_scan` (fetch results), and `ask` (NLWeb-compatible search over the Agent Ready glossary, guides, and methodology). Server card: <https://agent-ready.dev/.well-known/mcp/server-card.json>. Compatible with Claude Desktop, Cursor, Cline, Continue, Goose, and any MCP client that speaks streamable-http.

## API reference

Full OpenAPI 3.1 spec: <https://agent-ready.dev/api/v1/openapi.json> (alias <https://agent-ready.dev/openapi.json>).

Public endpoints:

- `POST /api/v1/scans` — start a scan. Body: `{"url": "https://example.com"}`.
- `GET /api/v1/scans/{id}` — fetch scan status and results.
- `POST /api/v1/ask` — NLWeb-compatible search over Agent Ready content. Body: `{"query": "what is llms.txt?"}`.
- `POST /api/v1/mcp` — MCP streamable-http endpoint. Same Bearer token, same rate-limit budget.

Rate limits: **10 req/min, 200 req/day per key** (sliding window). The OpenAPI spec is also advertised from the homepage via an RFC 8288 `Link` header with `rel="service-desc"`.

## Authentication summary

- **Auth header:** `Authorization: Bearer <key>`
- **Issue keys at:** <https://agent-ready.dev/dashboard/api-keys>
- **Discovery document:** <https://agent-ready.dev/.well-known/oauth-protected-resource>
- **Full walkthrough:** <https://agent-ready.dev/auth>

## Frequently asked questions

### Do I need to sign up to run a scan?

No — anonymous one-off scans run from the homepage at https://agent-ready.dev/ without sign-up (3 scans per IP per 30 days). To use the REST API or MCP server, you need a Pro account and an API key from /dashboard/api-keys.

### How long does a scan take?

Free tier scans complete in 5-15 seconds (25 pages). Pro scans complete in 15-60 seconds (250 pages). The /api/v1/scans response returns immediately with a scan id; poll /api/v1/scans/{id} until the status field flips from queued to complete. There is no webhook callback yet.

### Can I use the same API key for REST and MCP?

Yes — the same Bearer token authenticates POST /api/v1/scans, GET /api/v1/scans/{id}, POST /api/v1/ask, and POST /api/v1/mcp. The per-minute (10) and per-day (200) rate-limit budgets are shared across all surfaces.

### What does the MCP server expose?

Three tools: scan_site (start a scan), get_scan (fetch results), and ask (NLWeb-style search over the Agent Ready glossary, guides, and methodology). The server card at /.well-known/mcp/server-card.json describes the full surface in SEP-1649 format. Claude Desktop, Cursor, Cline, and other MCP clients can install it from the card URL.

### Where is the OpenAPI spec?

OpenAPI 3.1 at https://agent-ready.dev/api/v1/openapi.json (alias: /openapi.json). The spec covers every public endpoint, request schema, response schema, and authentication requirement. Use it with OpenAPI codegen (openapi-typescript, openapi-generator, swagger-codegen) to produce a typed client in your language of choice.

---

Authentication walkthrough: <https://agent-ready.dev/auth>

Pricing: <https://agent-ready.dev/pricing>

Read the full guide on the web: <https://agent-ready.dev/quickstart>

## Sitemap

See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.