# API, MCP, WebMCP and CLI

Agent-Ready Check is agent-ready itself: everything the web page does, an agent can do through a documented interface.

## HTTP API

The OpenAPI 3.1 description is at https://isainative.dev/openapi.json, listed in the API catalog at https://isainative.dev/.well-known/api-catalog (RFC 9727).

```bash
curl -s -X POST https://isainative.dev/api/scan -H 'content-type: application/json' -d '{"url":"https://example.com"}'
curl -s "https://isainative.dev/api/scan?url=example.com&format=markdown"
curl -s -X POST https://isainative.dev/api/scan -H 'content-type: application/json' -d '{"url":"https://example.com","format":"agent"}'
curl -s https://isainative.dev/api/checks
curl -s https://isainative.dev/api/checks/crawl.content-signal
curl -s https://isainative.dev/api/reports/REPORT_ID
```

- Formats: `json` (the full report), `markdown` (the report as Markdown) and `agent` (only the failing and warning checks, as fix prompts for a coding agent).
- Errors are `application/problem+json` (RFC 9457).
- Rate limit: scans per client per window, announced with `RateLimit-Policy` and `RateLimit` (draft-ietf-httpapi-ratelimit-headers-11). Over the limit you get 429 with `Retry-After`.
- The same URL is answered from a 10-minute cache. Reports are stored for 30 days at `/r/REPORT_ID` (HTML, or Markdown with `Accept: text/markdown`).

## MCP server

Stateless Streamable HTTP at https://isainative.dev/mcp. Protocol 2026-07-28 (with `server/discover`), and the 2025-11-25 and 2025-06-18 handshakes. No sessions; JSON responses. Server card: https://isainative.dev/mcp/server-card (also at /.well-known/mcp/server-card.json).

| Tool | Input | What it does |
| --- | --- | --- |
| `scan_site` | `url`, optional `browser` | Scans a site; returns a summary, the report URL and the full report as structured content |
| `list_checks` | optional `layer` | Lists the checks |
| `explain_check` | `id` | Explains one check: standard, status, why, fix |
| `get_report` | `id` | Returns a stored report |

```bash
curl -s https://isainative.dev/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2026-07-28' -H 'mcp-method: tools/call' -H 'mcp-name: scan_site' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"scan_site","arguments":{"url":"https://example.com"}}}'
```

## WebMCP

The home page registers a `scan_site` tool with `document.modelContext.registerTool()` and declares the scan form as a tool (`toolname`), so an agent in the browser can run a scan without clicking.

## CLI

```bash
npx agent-ready-check https://example.com
npx agent-ready-check https://example.com --json > report.json
npx agent-ready-check https://example.com --md
npx agent-ready-check https://example.com --prompts
npx agent-ready-check https://example.com --browser
npx agent-ready-check http://localhost:3000 --allow-private --fail-under 80 --level-at-least 3
npx agent-ready-check https://example.com --only crawl.robots-txt,content.llms-txt
```

The exit code is 1 when `--fail-under` or `--level-at-least` is not met, so the CLI works as a CI gate.

## Badges

```markdown
![Agent-Ready Check](https://isainative.dev/badge/example.com.svg)
```

A badge shows the latest stored report for the host. It never starts a scan.

## Agent discovery files

- robots.txt with named AI crawler groups, Content-Signal and Agentmap: https://isainative.dev/robots.txt
- llms.txt and llms-full.txt: https://isainative.dev/llms.txt
- Sitemap: https://isainative.dev/sitemap.xml
- API catalog: https://isainative.dev/.well-known/api-catalog
- MCP server card: https://isainative.dev/.well-known/mcp/server-card.json
- Agent Skills index: https://isainative.dev/.well-known/agent-skills/index.json
- ARD manifest: https://isainative.dev/.well-known/ard.json
- security.txt: https://isainative.dev/.well-known/security.txt
