Agent Cards and .well-known for AI Agents

Short answer. AI agents look for machine-readable "business cards" on your site in the /.well-known/ directory: agent-card.json (Google A2A), ai-plugin.json (plugins), mcp/server-card.json (Model Context Protocol), and agents.json. Together with llms.txt at your site root, they tell an agent what you do, which API документацию you expose, and how to interact with you. This is the new "SEO for agents" layer — without it, an agent sees only raw HTML.

What .well-known is and why agents need it

The /.well-known/ directory is a standardized location (RFC 8615) where services publish metadata about themselves: from SSL verification to OpenID configuration. AI agents reuse the same mechanism to find a description of your site's capabilities at a predictable path, without parsing your whole navigation.

A human reads your About page. An agent reads /.well-known/agent-card.json. If there's no card, the agent guesses from HTML — and guesses are sometimes wrong.

Key files and their roles

File	Purpose	Who uses it
agent-card.json	Agent description: skills, URL, protocol version	Google A2A, agent frameworks
ai-plugin.json	Plugin manifest: name, description, API entry point	Plugin-compatible assistants
mcp/server-card.json	MCP server card: tools and resources	MCP clients (Claude and others)
agents.json	Catalog of available agents/actions	General-purpose agents
llms.txt (at root)	Human- and machine-readable site map for LLMs	All AI crawlers

Example agent-card.json

A minimal, correct agent card per the A2A spec includes the protocol version and a skills description:

{
  "protocolVersion": "0.2.0",
  "name": "enterno.io",
  "description": "Website diagnostics and uptime monitoring tools",
  "url": "https://enterno.io",
  "capabilities": {
    "streaming": false
  },
  "securitySchemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key"
    }
  },
  "skills": [{
    "id": "http-check",
    "name": "HTTP header check",
    "description": "Analyze response headers and redirects"
  }]
}

The file is served at https://example.com/.well-known/agent-card.json and must return Content-Type: application/json.

The mcp/server-card.json idea

If you run an MCP server, a card at /.well-known/mcp/server-card.json describes the available tools and resources so an MCP client can discover them without manual setup:

{
  "name": "enterno-mcp",
  "version": "1.0.0",
  "description": "MCP server with website-check tools",
  "endpoint": "https://enterno.io/mcp",
  "tools": [
    { "name": "check_http", "description": "Check HTTP headers of a URL" },
    { "name": "check_ssl", "description": "Check an SSL certificate" }
  ]
}

The card is the "table of contents" of your MCP server: a client reads it, learns the tool list, and connects to the working endpoint.

How agents find and read cards

• The agent requests /.well-known/agent-card.json at the predictable path.
• In parallel it reads llms.txt at the root for a content map.
• If MCP is present, it fetches mcp/server-card.json for the tool list.
• You can mirror these hints in an HTTP Link: header pointing at the files.

The less an agent has to guess, the more accurately it represents your service in the user's answer. Cards remove the guesswork.

Agent-readiness checklist

• llms.txt at the site root, current and complete.
• /.well-known/agent-card.json with protocolVersion and securitySchemes.
• ai-plugin.json if you offer a plugin-compatible API.
• mcp/server-card.json if you run an MCP server.
• All files return valid JSON and Content-Type: application/json.
• AI crawlers are allowed in robots.txt (GPTBot, ClaudeBot, PerplexityBot, etc.).

FAQ

Are agent cards required right now?

No, they aren't a mandatory standard yet. But early adoption is an advantage: agents that already read them represent your service more accurately, and you won't lose visibility as agent traffic grows.

How is agent-card.json different from llms.txt?

llms.txt is a map of your content for LLMs (what to read). agent-card.json describes your capabilities and API for agents (what they can do). They complement each other.

Do I need my own MCP server?

Not everyone does. MCP makes sense if you want to give agents active tools (API calls), not just readable content. For a content site, llms.txt and an agent card are enough.

How do I verify everything is set up correctly?

Use an AI-readiness check — it verifies the presence and validity of llms.txt and the cards in .well-known. See also our guide on robots.txt for AI-crawler access.

Related reading: robots.txt and AI crawlers, structured data for SEO.

Check your AI readiness →