AIScan.site
Capability Checks

Capability Checks

P1 api-catalog, P2 MCP Server Card, P3 Agent Skills, P4 OAuth discovery.

The Capabilities dimension is where reading turns into doing. Each check here exposes a machine-readable manifest of what an agent can call on your site — APIs, tools, skills, and the OAuth flow they need to do it authenticated.

P1 — API Catalog (RFC 9727) (weight 4)

RFC 9727 defines /.well-known/api-catalog — a Linkset document listing every API your site exposes.

How to fix

# /.well-known/api-catalog
{
  "linkset": [
    {
      "anchor": "https://example.com/",
      "service-desc": [
        { "href": "https://example.com/api/openapi.json", "type": "application/openapi+json" }
      ]
    }
  ]
}

Pair with a Link header (D3) for instant discovery.

P2 — MCP Server Card (weight 5)

Model Context Protocol lets an agent connect to your site as if it were a tool runtime. The convention AIScan checks for: a server card at /.well-known/mcp/server-card.json describing the available tools, resources, and prompts.

How to fix

Implement an MCP server (HTTP transport works for most web apps), then publish a server card. See our own live example at /.well-known/mcp/server-card.json. Read MCP Server for the full integration guide.

P3 — Agent Skills bundle (weight 4)

Agent Skills are a portable JSON/Markdown bundle that teaches Claude Code (and compatible runtimes) when to use your service and how to call it. AIScan checks for a discoverable aiscan-skill.json-style bundle plus an accompanying CLAUDE.md.

How to fix

See Agent Skill & CLAUDE.md for the format, plus our own files at /aiscan-skill.json and /CLAUDE.md as a reference.

P4 — OAuth protected-resource metadata (weight 3)

For authenticated APIs, agents need to know which OAuth authorisation server to talk to. RFC 9728 defines /.well-known/oauth-protected-resource for exactly that.

How to fix

# /.well-known/oauth-protected-resource
{
  "resource": "https://example.com/api",
  "authorization_servers": ["https://auth.example.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["read", "write"]
}

Required only if your site has authenticated APIs — otherwise the check is N/A.

E2 — Machine-readable API description (weight 3, recommended)

If your site exposes endpoints, agents shouldn't have to reverse-engineer them. AIScan looks for /openapi.json, /openapi.yaml, /api/openapi.json, /.well-known/openapi.json, /swagger.json, or a service-desc link in your RFC 9727 API catalog.

On sites we detect as pure content sites, this is reported as an optional improvement rather than a failure — the report says so explicitly instead of silently dropping the check.

How to fix

# 1. Publish the spec
GET /openapi.json  ->  200 application/json (OpenAPI 3.1)

# 2. Advertise it
Link: </openapi.json>; rel="service-desc"; type="application/json"

Ours is at /openapi.json, linked from /.well-known/api-catalog.

Further reading