Make your site agent-callable: MCP, Agent Skills, A2A

Making your site agent-callable means publishing machine-readable discovery points — an MCP Server Card, an Agent Skills index, an A2A Agent Card — on top of the content agents can already read. The first wave of the "AI-friendly web" was about readability: robots.txt, llms.txt, Markdown mirrors, structured data, Link headers. That helps an agent understand your page. Getting it to act — place an order, run a calculator, kick off a workflow — is a different job. The agent has to know, in advance, what it can call, over which protocol, at which endpoint, at what version, and under which limits.

One caveat up front, because this space moves fast. As of June 2026, most of these standards are still settling. MCP Server Cards live in an experimental extension, not the frozen core spec, and WebMCP is a W3C Community Group draft whose API surface keeps shifting (Model Context Protocol roadmap). So treat what follows as the direction the market is already moving in, not a finished standard to copy verbatim.

Key takeaways

• Readable vs callable. A readable web helps an agent understand your content; a callable web lets it run your workflow. The callable layer is discovery: cards and manifests that declare what can be invoked, where, and how.
• An MCP Server Card is a discovery document, not a handshake replacement and not a tool list. The current experimental schema carries identity (name, description, version) plus remotes (transport type + url); tools are discovered at runtime.
• Agent Skills advertise procedures, not transport. A /.well-known/agent-skills/index.json lists skills by name, description, url, and digest, and agents load them progressively.
• A2A Agent Cards describe a remote agent as a peer service at /.well-known/agent-card.json (renamed from the older agent.json). WebMCP makes a page's tools callable in the browser.
• Adoption is tiny: Cloudflare found MCP Server Cards and API Catalogs on fewer than 15 of 200,000 sites (Cloudflare, 2026). Scan your domain to see which layers an agent finds today.

From readable to callable: what actually changes?

The shift is from comprehension to invocation. A2A's own specification draws the line cleanly: MCP standardizes how an agent connects to tools, APIs, and data sources, while A2A standardizes how independent agents communicate with each other (A2A Protocol). MCP is "how an agent uses a capability"; A2A is "how one agent finds and calls another as a peer."

In practice the two stack. An A2A agent accepts a task, then reaches for MCP internally to call the tools and data it needs. So these aren't competing standards — they're different floors of the same building, and most real architectures use more than one.

Here's the formula worth keeping: a readable web helps an agent understand your content; a callable web helps an agent execute your workflow. The first earns you a citation or a mention. The second turns your site, app, or API into an operating surface that agentic systems can actually drive.

None of this pays off without the readable layer underneath it. If an agent can't fetch and parse your pages in the first place — the ground covered in what AI agent readiness means — a flawless manifest changes nothing. Callable is the next floor up, not a replacement for the foundation.

What is an MCP Server Card, and where does it live?

An MCP Server Card is a small JSON document that lets a client learn about a remote MCP server, its identity and how to reach it, before the full handshake. Two things keep tripping people up: where it lives, and what belongs inside it.

Where it lives: mind the path drift

The path is where you have to be careful, because there's genuine version drift. The early SEP-1649 draft proposed /.well-known/mcp.json, which is why "well-known mcp.json" gets searched and quoted today. But that work moved into the SEP-2127 line.

The current experimental extension shifts the emphasis again. The card can sit at any unreserved URI, and GET <streamable-http-url>/server-card is reserved for transport-level discovery. Clients are meant to learn the card's URL through a catalog rather than guess a well-known path (SEP-1649, experimental schema). So don't present /.well-known/mcp.json as the settled standard. For June 2026 that's too definite.

What goes in the card

The shape has shifted too. The early narrative centered on serverInfo, protocolVersion, transport, and capabilities. The current experimental ServerCard schema reads more like registry metadata: $schema, name, description, and version are required. Remote endpoints go in remotes, where each entry needs a type and url (supportedProtocolVersions and headers are optional).

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
  "name": "com.example/weather",
  "description": "Remote MCP server for weather lookups and forecasts.",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://api.example.com/mcp",
      "supportedProtocolVersions": ["2025-06-18"]
    }
  ]
}

Here's the part most write-ups get wrong: the card is a discovery layer, not a registry of every tool. The SEP-2127 discussion deliberately keeps primitive listings (tools, resources, prompts) out of the card, because a static manifest drifts from a live surface that depends on auth, feature flags, and configuration (discovery issue).

At runtime the server still negotiates protocolVersion and capabilities and answers list operations (MCP schema); the card just gets a client to the door. Its own schema even calls its fields advisory, not the authoritative basis for security decisions.

What do Agent Skills advertise?

Agent Skills answer a different question: not "where do I connect?" but "what procedure should I follow when working with you?" A skill is a directory with a required SKILL.md and optional scripts/, references/, and assets/. Its YAML front-matter requires a name and a description, and that description tells the agent both what the skill does and when to use it (Agent Skills specification).

For web discovery, Cloudflare's RFC adds an index at /.well-known/agent-skills/index.json. In v0.2.0 it carries a $schema and a skills array, where each entry requires name, type, description, url, and digest (agent-skills-discovery-rfc). The digest is a SHA-256 a client uses to verify the artifact it downloads.

{
  "$schema": "https://schemas.cloudflare.com/agent-skills/index/v0.2.0.json",
  "skills": [
    {
      "name": "scan-url",
      "type": "skill-md",
      "description": "Run an agent-readiness scan on a public URL and read the 0–100 score.",
      "url": "https://example.com/.well-known/agent-skills/scan-url/SKILL.md",
      "digest": "sha256:7d8f…"
    }
  ]
}

What makes this scale is progressive disclosure. The agent first loads the light catalog, just names and descriptions. If a task matches, it pulls the full SKILL.md. Only then, and only if needed, does it read the referenced files, scripts, and assets. An agent can know about dozens of skills without burning context on all of them at once.

So Agent Skills are a manifest of application, not invocation. They don't advertise a transport or an endpoint — they teach a procedure: how to call your API correctly, how to negotiate Markdown (see serve Markdown to AI agents), how to run a checkout, how to respect your rate limits. The card says what you have; the skill says how to use it well.

A2A Agent Cards and WebMCP: where do they fit?

If an MCP Server Card describes a tool surface, an A2A Agent Card describes a remote agent as a network peer. In A2A 1.0 a client looks for it at https://{domain}/.well-known/agent-card.json, now registered as a permanent well-known suffix. Mind the drift: earlier A2A used /.well-known/agent.json; current releases use agent-card.json (A2A Protocol, A2A v0.2.0). It's a textbook example of why version-aware wording matters.

The card is richer than a name and a blurb. A2A 1.0 includes name, description, version, supportedInterfaces (each with url, protocolBinding, and protocolVersion), capabilities, securitySchemes, security, defaultInputModes, defaultOutputModes, and skills, plus optional provider, documentationUrl, signature, and iconUrl. That's a full service description, not low-level tool discovery.

A clean way to keep the three apart:

WebMCP: tools in the browser

WebMCP needs the most careful wording of all. The published W3C draft exposes its API through document.modelContext: a Document gains a modelContext, which has registerTool() and a toolchange event. It runs only in secure contexts, ties into Permissions Policy with a default 'self' allowlist, and lets a tool set its visibility per origin via exposedTo (WebMCP draft). This isn't "the LLM reads the DOM." It's a browser-native way to publish callable tools.

// WebMCP — the published draft surface (still evolving)
document.modelContext.registerTool({
  name: "add_to_cart",
  description: "Add a product to the cart by SKU.",
  // inputSchema, execute handler, …
});

But navigator.modelContext, the name you may have run into, isn't a myth either. The WebML Community Group minutes record a resolution naming navigator.modelContext the root object, and the group is weighing how external agents should list and call a page's tools (WebML CG minutes). The honest summary? The draft today still leads with document.modelContext.registerTool(), while the working direction is a more general browser-level object. Write that, and your guide won't read as wrong next quarter.

How does this relate to API discovery and OpenAPI?

It builds on it. Agent discovery doesn't replace classic API discovery. It sits above it. RFC 9727 standardizes /.well-known/api-catalog as the URI where a client fetches a document linking to your published APIs and their descriptions, instead of guessing OpenAPI file locations or scraping HTML docs (RFC 9727). OpenAPI then describes each HTTP API in machine- and human-readable form, so a client understands the surface and its semantics without reading source or sniffing traffic (OpenAPI 3.2.0).

Each layer answers exactly one question. That's the whole mental model:

Put plainly: do API discovery and your surface becomes discoverable; do MCP, A2A, or WebMCP and it becomes callable; publish Agent Skills and it becomes correctly usable. No standards war required; they're floors in the same building, and you fit out the ones your product needs. A content site might stop at the readable layer; a checkout API or an agentic service climbs higher.

What are the most common mistakes?

The top failure is describing an unstable discovery point as if it were canonical, and MCP is where it bites hardest. Five patterns show up again and again:

• Phantom manifests. Writing "the MCP standard requires this exact path" when /.well-known/mcp.json, /.well-known/mcp/server-card.json, /.well-known/mcp-server, and catalog-based discovery all coexist. Use version-aware wording, and check what your client or validator actually expects.
• Stuffing the card with a tool list. Primitive listings were pulled out of the Server Card on purpose. A static list desyncs from the live, auth-dependent surface and breeds wrong security assumptions.
• A pretty manifest with no working endpoint or version. A remote needs at least a type and a url; A2A supportedInterfaces need url, protocolBinding, and protocolVersion. Discovery without transport and versioning isn't a callable interface — it's a JSON poster.
• Treating Agent Skills as another endpoint. A skill declares no transport and no binding. It's an instruction bundle loaded progressively, a different layer from MCP or your API.
• Ignoring version drift. A2A's agent.json became agent-card.json; WebMCP splits between document.modelContext and navigator.modelContext. Skip these transitions and your guide ages into phantom paths within a quarter.

The thread tying all five together: discovery is only useful when it resolves to something real and versioned. A manifest that can't be connected to is decoration.

How do you verify your site is agent-callable?

You check it the way an agent would: fetch each discovery point and confirm it parses, resolves to a real endpoint, and carries a version. That's a finite, checkable list, which is exactly what a scan is for. aiSiteReady's protocol & API category maps onto this article almost one-to-one. It runs an MCP Server Card check, an Agent Skills index check, an A2A / WebMCP readiness check, and an API Catalog check. Those sit alongside the roughly 15–20 checks that roll up into an Agent Readiness Score from 0 to 100. The exact checks and weights live on the methodology page.

And the adoption gap is the opportunity. In April 2026 Cloudflare reported that standards like MCP Server Cards and API Catalogs appeared on fewer than 15 sites in a 200,000-domain sample (Cloudflare, 2026). The readable-web layer is crowded now; this one isn't, and early movers still have room.

We built these checks against our own stack, which kept us honest. aiSiteReady ships a real MCP server with a Server Card, an Agent Skills index backed by a working SKILL.md, and an RFC 9727 API Catalog that points at a public OpenAPI document. Open /.well-known/agent-skills/index.json on this domain and check. Building the scanner forced us through every spec above; this guide is the version-tolerant map we wish we'd had on day one.

A short checklist to finish on:

• Have a classic HTTP API? Publish an API Catalog and link your OpenAPI docs.
• Have a remote MCP surface? Publish an MCP Server Card with transport and version metadata, not just a name.
• Publish a remote agent? Add an A2A Agent Card at the current well-known path.
• Want agents to use your product correctly? Publish an Agent Skills index and real SKILL.md files.
• Live in the browser with user-facing actions? Experiment with WebMCP to make the page directly callable.

Then run a free scan: it fetches your domain the way an agent would and shows which layers it actually found, with fixes ranked by impact — no sign-up, any public URL, results in English, Ukrainian, or Russian. The score is a readiness diagnostic, not a guarantee of anything downstream.

The one line to remember: the next stage of the web for AI isn't just sites that are pleasant to read — it's sites and apps that can be reliably discovered, understood, and called over standard layers. Readable got you cited. Callable gets you used.

IMozz has 20 years in software development, with the past year spent building with LLMs. He builds aiSiteReady, a read-only scanner that checks whether AI agents can read and call a site, and it publishes its own MCP Server Card and Agent Skills index as a working example.