SEP 0014 - AI Card Discovery

[Fannon]

This SEP proposes a standardized discovery mechanism for AI-native protocols (MCP and A2A) using a .well-known URI endpoint.

It makes a strong assumption that MCP and A2A do not create a shared model, each will own its own "card" metadata files. But we can still share the discovery mechanism between the two (and potentially other / upcoming) protocols.

Problem

Both MCP and A2A protocols have defined protocol-specific discovery endpoints that:

• Assume one server/agent per host (MCP: /.well-known/mcp/server-card.json, A2A: /.well-known/agent.json)
• Require clients to probe multiple endpoints for multi-protocol discovery
• Create ecosystem fragmentation

Solution

A single, protocol-agnostic discovery endpoint at /.well-known/ai-cards.json that:

• Supports multiple MCP servers and/or A2A agents per host
• Enables single-request multi-protocol discovery
• Maintains protocol autonomy (each protocol owns its card format)
• Uses simple JSON Schema with 5 required fields per protocol
• Supports both relative and absolute URLs

Example

{
  "$schema": "https://ai-card.org/schemas/ai-card-v0.schema.json",
  "protocols": [
    {
      "type": "mcp",
      "endpoints": [{"url": "./mcp-petstore"}],
      "metadata": {
        "type": "mcp-server-card",
        "url": "./petstore.mcp.json"
      }
    },
    {
      "type": "a2a",
      "endpoints": [{"url": "/agents/support"}],
      "metadata": {
        "type": "agent-card",
        "url": "/metadata/SupportAgent.json"
      }
    }
  ]
}

[Fannon]

URL to be decided yet, just a placeholder for the real URL later.

[Fannon]

There are also some situations where implementing a .well-known URI is not possible, e.g. if the provider does not have control over the root URLs of the host. In that case a DNS based approach could be an alternative - however most providers won't have easy access to setup DNS entries, too...

I assume that most registries would also allow push based publishing, which is an alternative to the .well-known URI approach, but it would not provide the local, decentralized discovery.

[Fannon]

This is actually debatable: Not everyone can control the host root URL and add a .well-known URI like this.

A more pragmatic approach could be to make this just RECOMMENDED. For fully decentralized discovery doing this might be mandatory, but if your goal is to register your AI systems with a registry or other systems, it could be sufficient to provide a full link to the discovery document URL. A registry could auto-append /.well-known/ai-cards.json if a system is added via hostname, or directly crawl the URL if a URL with path segments is provided.

Suggested change

	Services supporting AI Card discovery MUST provide a JSON document at `/.well-known/ai-cards.json`.
	Services supporting AI Card discovery MUST provide the [Discovery Document](#discovery-document-format) and SHOULD provide it under `/.well-known/ai-cards.json`.
	If this is not possible, completely decentralized discovery is not supported, but the discovery document URL can still be registered in registries and other systems.

[Fannon]

Ideally create a small plugin for an existing Agent Framework that supports both MCP and A2A.
Challenge here is that for MCP we still have the missing MCP Server Card as gap.

A minimalist implementation could be just a static web server that serves the JSON files as defined here. This would be sufficient to test that the discovery mechanisms work in principle.

[darrelmiller]

Here's my rant on why we need to stop using .well-known #17