From 900cb89946bc81982ed42398c51f957ee8a630d0 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 27 May 2026 16:38:28 -0700
Subject: [PATCH] a2a card and discovery endpoints

---
 ai/model-context-protocol.mdx |  2 ++
 ai/skillmd.mdx                | 14 ++++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx
index 9926b72123..caf7aa3330 100644
--- a/ai/model-context-protocol.mdx
+++ b/ai/model-context-protocol.mdx
@@ -116,6 +116,8 @@ Mintlify hosts a discovery document at `/.well-known/mcp` for agents and tools t
 | `servers[].name` | Identifier for the server entry. |
 | `servers[].authentication` | Authentication method for the server entry. |
 
+For agent-readiness, the same discovery document is also available at `/.well-known/mcp.json`. Mintlify additionally serves an MCP server card at `/.well-known/mcp/server-card.json` and a list of server cards at `/.well-known/mcp/server-cards.json`. All discovery endpoints are served automatically and don't require configuration.
+
 ### Enable authenticated MCP
 
 If your documentation requires authentication, your MCP server requires users to authenticate before connecting. When a user adds your MCP server URL to their AI tool, they must log in with their existing credentials. After authenticating, a redirect sends them back to their tool. The MCP server only returns content each user has permission to access based on their [user groups](/deploy/authentication-setup).
diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index a813a75202..b1a0f56278 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -191,3 +191,17 @@ The `name` field is a URL-safe slug derived from the `name` in your `skill.md` f
 ### Individual skill files
 
 `GET /.well-known/skills/{name}/skill.md` returns the `skill.md` file for a specific skill identified by its slugified name from the index.
+
+## Agent card
+
+Mintlify hosts an [Agent-to-Agent (A2A)](https://a2aproject.github.io/A2A/latest/) agent card at `/.well-known/agent-card.json`. The agent card is a standardized JSON document that helps A2A-compatible agents discover your documentation site and available skills in a single request.
+
+`GET /.well-known/agent-card.json` returns a JSON document following the A2A agent card 0.2.0 schema. Each entry in the `skills` array corresponds to a skill from your skills discovery endpoints.
+
+A2A-compatible agents fetch `/.well-known/agent-card.json` to discover your site by name and description, follow `documentationUrl` to retrieve human-readable content, and iterate over `skills` to fetch each `skill.md` file.
+
+<Note>
+  If you use a [reverse proxy](/deploy/reverse-proxy), configure it to forward `/.well-known/agent-card.json` to your Mintlify subdomain.
+</Note>
+
+The agent card complements [MCP](/ai/model-context-protocol) by providing a lightweight discovery layer that does not require establishing a session.