diff --git a/seps/0000-ai-card-discovery.schema.json b/seps/0000-ai-card-discovery.schema.json new file mode 100644 index 0000000..5f17476 --- /dev/null +++ b/seps/0000-ai-card-discovery.schema.json @@ -0,0 +1,127 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://ai-card.org/schemas/ai-card-v0.schema.json", + "title": "AI Card Discovery Document", + "description": "Discovery document for AI-native protocols (MCP, A2A, etc.) exposed by a host via /.well-known/ai-cards.json", + "type": "object", + "required": ["protocols"], + "properties": { + "$schema": { + "type": "string", + "description": "URI reference to the JSON Schema for this document", + "format": "uri", + "examples": [ + "https://ai-card.org/schemas/ai-card-v0.schema.json" + ] + }, + "protocols": { + "type": "array", + "description": "Array of protocol objects describing AI-native protocols (servers/agents) available on this host. A single host can expose multiple MCP servers and/or multiple A2A agents.", + "minItems": 1, + "items": { + "$ref": "#/$defs/protocol" + } + } + }, + "additionalProperties": false, + "$defs": { + "protocol": { + "type": "object", + "description": "Describes a single MCP server or A2A agent exposed by this host", + "required": ["type", "endpoints", "metadata"], + "properties": { + "type": { + "type": "string", + "description": "The AI protocol type identifier. Current values: 'mcp' for Model Context Protocol servers, 'a2a' for Agent-to-Agent agents. Future AI protocols may be added.", + "enum": ["mcp", "a2a"], + "examples": ["mcp", "a2a"] + }, + "endpoints": { + "type": "array", + "description": "Array of endpoint objects where this protocol server/agent can be accessed", + "minItems": 1, + "items": { + "$ref": "#/$defs/endpoint" + } + }, + "metadata": { + "$ref": "#/$defs/metadata", + "description": "Reference to the protocol-specific card metadata file (MCP Server Card or A2A Agent Card)" + } + }, + "additionalProperties": false, + "examples": [ + { + "type": "mcp", + "endpoints": [ + { + "url": "https://example.com/mcp/petstore" + } + ], + "metadata": { + "type": "mcp-server-card", + "url": "https://example.com/.well-known/petstore.mcp.json" + } + }, + { + "type": "a2a", + "endpoints": [ + { + "url": "https://api.example.com/agents/customer-service" + } + ], + "metadata": { + "type": "agent-card", + "url": "https://api.example.com/.well-known/CustomerServiceAgent.json" + } + } + ] + }, + "endpoint": { + "type": "object", + "description": "A single endpoint URL where the protocol can be accessed", + "required": ["url"], + "properties": { + "url": { + "type": "string", + "description": "The endpoint URL where this protocol server/agent can be accessed. May be absolute (https://...) or relative (./path, /path). Relative URLs are resolved relative to the location of the discovery document (/.well-known/ai-cards.json). For example, ./mcp-endpoint resolves to /.well-known/mcp-endpoint, and /api/mcp resolves to /api/mcp.", + "pattern": "^(https?://|/|\\./)", + "examples": [ + "https://example.com/mcp-endpoint", + "https://api.example.com/agents/customer-service", + "/api/mcp", + "./mcp-endpoint", + "../mcp/server" + ] + } + }, + "additionalProperties": false + }, + "metadata": { + "type": "object", + "description": "Reference to protocol-specific card metadata. The structure of the metadata file is owned and defined by the protocol community (MCP or A2A). This SEP only defines the discovery mechanism.", + "required": ["type", "url"], + "properties": { + "type": { + "type": "string", + "description": "The metadata card type. Identifies the format/schema of the metadata file. Current values: 'mcp-server-card' for MCP Server Cards, 'agent-card' for A2A Agent Cards. Future card types may be added.", + "enum": ["mcp-server-card", "agent-card"], + "examples": ["mcp-server-card", "agent-card"] + }, + "url": { + "type": "string", + "description": "URL to the protocol-specific card metadata file. May be absolute (https://...) or relative (./path, /path). Relative URLs are resolved relative to the location of the discovery document (/.well-known/ai-cards.json). For example, ./petstore.mcp.json resolves to /.well-known/petstore.mcp.json. For MCP: points to an MCP Server Card. For A2A: points to an A2A Agent Card.", + "pattern": "^(https?://|/|\\./)", + "examples": [ + "https://example.com/.well-known/petstore.mcp.json", + "https://api.example.com/metadata/CustomerServiceAgent.json", + "./petstore.mcp.json", + "./PetAgent.json", + "/metadata/inventory.mcp.json" + ] + } + }, + "additionalProperties": false + } + } +} diff --git a/seps/0014-ai-card-discovery.md b/seps/0014-ai-card-discovery.md new file mode 100644 index 0000000..d194569 --- /dev/null +++ b/seps/0014-ai-card-discovery.md @@ -0,0 +1,383 @@ +--- +SEP: 0014 +Title: AI Card Discovery via Well-Known URI +Author: Simon Heimler +Status: draft +Type: Standards Track +Created: 2026-01-24 +--- + +## Abstract + +This SEP proposes a standardized discovery mechanism for AI native protocols and their metadata through a [.well-known URI](https://www.rfc-editor.org/rfc/rfc8615) endpoint (`/.well-known/ai-cards.json`). This solves the discovery problem that both [MCP](https://modelcontextprotocol.io) (Model Context Protocol) and [A2A](https://a2a-protocol.org) (Agent-to-Agent) protocols face, eliminating the need for each protocol to define its own discovery mechanism independently. + +The proposal recognizes that: +- **A2A** has defined [`/.well-known/agent.json`](https://github.com/protocol-registries/well-known-uris/issues/66) for discovery, but has a **single-service assumption** (one agent per host) +- **MCP Server Cards** need to evolve from the existing MCP Registry `server.json` format to include tools, prompts, and resources, proposed as [MCP Server Cards (SEP-2127)](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127), with discovery at `/.well-known/mcp/server-card.json` also having a **single-service assumption** (one server per host) +- Both protocols face the **same limitation**: the single-service assumption doesn't fit real-world multi-service deployments +- **Discovery** is a shared concern that benefits from a unified, multi-service approach +- **Future-proofing**: The discovery mechanism is designed to support future AI protocols, versions and their metadata formats + +By providing a protocol-agnostic discovery layer, this SEP enables a single host to advertise multiple MCP servers and/or multiple A2A agents, while allowing each protocol to maintain full ownership of their card formats, keeping their own autonomy and lifecycle. + +## Motivation + +### The Problem: Single-Service Assumption + +Both **A2A** and **MCP** are defining protocol-specific discovery mechanisms: +- **A2A**: [`/.well-known/agent.json`](https://github.com/protocol-registries/well-known-uris/issues/66) +- **MCP**: `/.well-known/mcp/server-card.json` ([SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)) + +Both share a critical **single-service assumption**: one agent or server per host. + +**This breaks down in real-world scenarios:** +- A host needs to expose multiple specialized services (e.g., petstore + inventory MCP servers, or sales + support A2A agents) +- A platform provides both MCP servers and A2A agents +- Registries ideally cover both both Agents and Tools (MCP) together, as agents often rely on external tools and other agents. + +### The Problem: Discovery Fragmentation + +Having separate protocol-specific endpoints creates additional friction: +- **Multiple probes required**: Clients must try `/.well-known/agent.json`, then `/.well-known/mcp/server-card.json`, then future protocols +- **N+1 HTTP requests**: One per protocol, with many failures for unsupported protocols +- **No capability indication**: No standard way to discover what AI protocols a domain supports +- **Duplicated standardization efforts**: Since MCP has not standardized yet how a .well-known discovery would work, going for AI Card discovery directly reduces one option for the ecosystem to support. + +### This Proposal + +This SEP provides a **single, protocol-agnostic discovery endpoint** (`/.well-known/ai-cards.json`) that: +1. Enables **multi-service discovery** (multiple MCP servers and/or A2A agents per host) +2. Enables **multi-protocol discovery** (single request reveals all AI capabilities) +3. Allows each protocol to **maintain full ownership** and separate lifecycle of their metadata formats + +## Specification + +### Well-Known URI + +Services supporting AI Card discovery MUST provide a JSON document at `/.well-known/ai-cards.json`. + +> By appending `.json` it is easier to host this and the linked metadata files on a static file server. + +### Discovery Document Format + +The discovery document MUST be a JSON object following the [ai-card-v0.schema.json](./0000-ai-card-discovery.schema.json) schema. + +```jsonc +{ + "$schema": "https://ai-card.org/schemas/ai-card-v0.schema.json", + "protocols": [ + // A2A agent example + { + "type": "a2a", + "endpoints": [{"url": "https://example.com/a2a-endpoint"}], + "metadata": { + "type": "agent-card", + "url": "https://example.com/.well-known/PetAgent.json" + } + }, + // First MCP server - petstore + { + "type": "mcp", + "endpoints": [{"url": "https://example.com/mcp-endpoint"}], + "metadata": { + "type": "mcp-server-card", + "url": "https://example.com/.well-known/petstore.mcp.json" + } + }, + // Second MCP server - inventory (demonstrates multi-service capability) + { + "type": "mcp", + "endpoints": [{"url": "https://example.com/mcp-endpoint-inventory"}], + "metadata": { + "type": "mcp-server-card", + "url": "https://example.com/.well-known/inventory.mcp.json" + } + } + ] +} +``` + +**Note**: A single host can expose multiple MCP servers or multiple A2A agents. Each should be listed as a separate entry in the `protocols` array, as shown in the example above where two different MCP servers (petstore and inventory) are hosted on the same domain. + +### URL Resolution + +URLs in the discovery document (both `endpoints[].url` and `metadata.url`) **MAY be relative or absolute**. + +#### Absolute URLs + +Absolute URLs include the full protocol and authority: +- `https://example.com/mcp-endpoint` +- `https://api.example.com/.well-known/petstore.mcp.json` + +#### Relative URLs + +Relative URLs are resolved **relative to the location of the discovery document** (`/.well-known/ai-cards.json`), following [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) URL resolution rules: + +**Path-relative URLs** (start with `./` or `../`): +- `./petstore.mcp.json` → resolves to `/.well-known/petstore.mcp.json` +- `./mcp-endpoint` → resolves to `/.well-known/mcp-endpoint` +- `../metadata/server.json` → resolves to `/metadata/server.json` + +**Absolute-path URLs** (start with `/`): +- `/api/mcp` → resolves to `/api/mcp` (relative to host root) +- `/metadata/petstore.mcp.json` → resolves to `/metadata/petstore.mcp.json` + +**Recommendation**: Use relative URLs when metadata and endpoints are co-located with the discovery document. Use absolute URLs when pointing to external services or different domains. + +### Metadata Files + +Each protocol community maintains **full ownership** of their metadata format. +The attached metadata files remain fully self-contained. +This SEP only defines the discovery mechanism that points to these files. + +#### Protocol-Specific Metadata Formats + +- **MCP Server Cards** (Defined by MCP community): + - Should evolve from the existing [MCP Registry `server.json` format](https://github.com/modelcontextprotocol/registry) ([JSON Schema](https://github.com/modelcontextprotocol/registry/blob/main/internal/validators/schemas/2025-12-11.json)) + - Enhanced with tools, prompts, and resources as proposed in [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) + - Full schema control remains with the MCP community + +- **A2A Agent Cards** (Defined by A2A specification): + - Already well-defined by the A2A specification + - Full schema control remains with the A2A community + +#### Scope of This SEP + +This SEP **intentionally does not mandate** any particular structure for metadata files. It only standardizes: +1. How to **discover** multiple AI protocols and metadata files on a single host +2. How to **identify** protocol and metadata format types (`type` field) +3. How to **locate** metadata files (`metadata.url` field) + +The scope could be expanded in the future to indicate version(s) of protocols and metadata formats (see Open Questions). + +## Rationale + +### Why Not a Shared Metadata Model? + +Rather than creating a unified card format for MCP and A2A, this SEP keeps card definitions protocol-specific to avoid: +- Ongoing coordination overhead between protocol groups +- Potential compromises that don't serve either protocol well +- Slower evolution requiring multi-party consensus + +### Integration with Existing Mechanisms + +This SEP coexists or supersedes protocol-specific discovery endpoints: +- A2A's `/.well-known/agent.json` (coexists) +- MCP's proposed `/.well-known/mcp/server-card.json` (SEP-2127) (supersedes) + +## Backward Compatibility + +This is a new feature and does not introduce backward compatibility concerns. Services that do not implement the well-known URI simply won't be discoverable through this mechanism. + +## Reference Implementation + +[To be provided] + +## Security Implications + +1. **HTTPS Required**: SHOULD require HTTPS for all URLs to prevent man-in-the-middle attacks +2. **Size Limits**: SHOULD enforce reasonable limits on discovery documents (e.g., 2MB) to prevent DoS attacks +3. **Access Control**: Well-known discovery entry-point SHOULD be unprotected; linked metadata files MAY be protected + +## Open Questions + +### 1. Protocol and Metadata Format Versioning Strategy + +**Question**: If a service supports multiple versions of a protocol (e.g., MCP v1 and v2) and metadata formats (e.g. Agent Card v1 and v2), how should this be represented? +Should the protocol `type` field include version information (e.g., `"mcp/v1"`, `"a2a/v2"`)? + +**Options**: +- **A)** Include in `type`: `"mcp/v1"`, `"a2a/v2"` +- **B)** Separate `version` field: `{"type": "mcp", "version": "1.0"}` +- **C)** Only in metadata files or protocol endpoint: Extract it from the linked metadata files or by connecting to endpoint where server will respond with the version(s) of the protocol it implements + +**Trade-offs**: +- Option A enables protocol version filtering without fetching metadata +- Option B provides structured versioning but adds a required field +- Option C keeps discovery simpler but requires metadata fetch to determine version + +### 2. Access Control for Metadata + +**Question**: Should the discovery document indicate when metadata requires authentication? +Do we have to support public and internal metadata (internal could be richer)? + +**Options**: +- **A)** Add `metadata.accessStrategy` field (e.g., `"public"`, `"oauth2"`, `"api-key"`) +- **B)** Clients discover through HTTP 401/403 responses +- **C)** No indication - assume public discovery, protected metadata requires docs + +### 3. Dynamic and Tenant-Specific Metadata + +**Question**: How should dynamic or tenant-specific metadata be handled? + +**Use case**: Multi-tenant SaaS where each tenant has different available tools/capabilities. + +**Options**: +- **A)** Allow dynamic generation of discovery document and metadata files +- **B)** Use query/header params or bearer token +- **C)** Document that discovery is static; dynamic capabilities in metadata files + +### 4. Metadata that is not tied to an API protocol + +**Question**: Should metadata that is not tied to an API protocol implementation be discoverable? Do we see use-cases for this? + +Examples: +- https://github.com/edp-protocol/entity-discovery-protocol + +### 5. Add lightweight shared model with public information to the discovery document? + +A few more field could be added to the discovery document to provide public information about the service, such as: +- ID / Name +- Short Description +- Links (to documentation, terms of service, etc.) + +## Alternatives Considered + +### Unified Card Model + +Creating a single card format that both MCP and A2A adopt. Proposal is to reject this due to the coordination overhead and risk of creating yet another standard. + +### Protocol-Specific Discovery (Status Quo) + +Having each protocol define its own discovery mechanism: +- MCP: `/.well-known/mcp/server-card.json` ([SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)) +- A2A: `/.well-known/a2a/agent-card.json` (proposed) + +**Advantages:** +- Each protocol has full control +- No cross-protocol coordination needed +- Simpler for single-protocol deployments + +**Disadvantages:** +- Clients must probe multiple endpoints to discover all capabilities +- Registries must crawl multiple endpoints per domain +- No standard way to discover what protocols a domain supports +- N+1 HTTP requests where N is the number of protocols + +**Integration Path:** +This SEP could be implemented **alongside** protocol-specific endpoints: +1. `/.well-known/ai-cards.json` serves as a directory +2. `metadata.url` points to protocol-specific endpoints like `/.well-known/mcp/server-card.json` +3. Single-protocol deployments can skip the directory and only implement their protocol-specific endpoint +4. Multi-protocol deployments and registries benefit from the unified discovery + +This allows gradual adoption without breaking existing protocol-specific discovery mechanisms. + +### DNS-Based Discovery + +Using DNS TXT records for discovery (similar to DKIM or SPF). +- Only works at domain level, not for path-based or port-based deployments +- Requires DNS infrastructure control +- More complex to implement and query +- Less accessible for web-based clients + +This approach could be rejected or be allowed as an alternative to the .well-known URI approach in the future. + +## Prior Art + +### Summary of Related Standards + +| Standard | Endpoint | Scope | Single/Multi-Service | Relationship to This SEP | +|----------|----------|-------|----------------------|-------------------------| +| **[A2A Agent Discovery](#a2a-well-knownagentjson)** | `/.well-known/agent.json` | A2A agents only | Single-service | This SEP enables multi-agent discovery | +| **[MCP SEP-2127](#mcp-sep-2127-mcp-server-cards---http-server-discovery)** | `/.well-known/mcp/server-card.json` | MCP servers only | Single-service | This SEP enables multi-server discovery | +| **[RFC 9727](#rfc-9727-well-knownapi-catalog)** | `/.well-known/api-catalog` | All API types | Multi-service | Generic, not AI-protocol-aware | +| **[ORD](#open-resource-discovery-well-knownopen-resource-discovery)** | `/.well-known/open-resource-discovery` | APIs, Events, Data Products | Multi-service | Enterprise-grade, broader scope than AI | + +### MCP SEP-2127: MCP Server Cards - HTTP Server Discovery + +[SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) proposes a comprehensive MCP Server Card format including: +- Server identification and versioning +- Transport configuration (streamable-http, stdio, SSE) +- Capabilities (tools, prompts, resources) +- Authentication requirements + +Proposed at `/.well-known/mcp/server-card.json` with a **single-server assumption**. + +**Relationship to this SEP:** +- SEP-2127 defines **what metadata to include** in server cards +- This SEP addresses **how to discover** multiple servers on a single host +- Discovery uses `/.well-known/ai-cards.json` pointing to individual server card files + +### MCP Registry server.json Format + +The [MCP Registry `server.json` format](https://github.com/modelcontextprotocol/registry/blob/main/internal/validators/schemas/2025-12-11.json) provides a foundation for MCP Server Cards but lacks tools, prompts, and resources. It should be enhanced (per SEP-2127) and made discoverable via `metadata.url`. + +### A2A: `/.well-known/agent.json` + +A2A has defined [`/.well-known/agent.json`](https://a2a-protocol.org/latest/specification/) ([IANA registration](https://github.com/protocol-registries/well-known-uris/issues/66)) for agent discovery. + +**A2A Agent Cards include:** +- Agent identification and metadata +- Capabilities and supported operations +- Authentication and authorization requirements +- Endpoint information + +**Relationship to this SEP:** +- A2A's card format remains **A2A-owned** and unchanged +- The single-agent assumption is addressed by this SEP +- `metadata.url` in the discovery document points to individual Agent Card files +- Enables discovery of **multiple agents** on a single host + +### RFC 9727: `/.well-known/api-catalog` + +[RFC 9727](https://datatracker.ietf.org/doc/rfc9727/) (IETF Standards Track, June 2025) defines generic API discovery using Linkset format for **any API type** (REST, GraphQL, SOAP). + +**Key differences from this SEP:** + +| Aspect | RFC 9727 | This SEP | +|--------|----------|----------| +| **Scope** | Generic APIs (REST, GraphQL, SOAP, etc.) | AI-native protocols (MCP, A2A) | +| **Protocol Awareness** | Protocol-agnostic, undefined | Protocol-specific (`type: mcp` vs `type: a2a`) | +| **Metadata** | Links to OpenAPI specs, generic docs | Links to AI-specific card formats (MCP Server Cards, A2A Agent Cards) | + +**Relationship**: RFC 9727 is too generic for AI protocol discovery. +It does neither state which protocol nor which metadata format is provided, just a generic MIME type. +This SEP provides AI-specific protocol identification and metadata. + +**Counterargument**: We could register a more precise MIME type for the AI protocol metadata formats (e.g. `application/a2a-agent-card+json`), making this approach work better (although still no protocol defined). + +### Open Resource Discovery: `.well-known/open-resource-discovery` + +[ORD](https://open-resource-discovery.org/spec-v1) (Linux Foundation) is an enterprise-grade discovery protocol for APIs, events, data products, domain objects, (business) taxonomy and more. + +**ORD capabilities include:** +- Multiple resource types and protocols supported (APIs, events, data products, agents, lightweight system landscape model) +- Includes defining and linking of taxonomies and business-concepts (vendors, products, domain / business objects) +- Static vs dynamic perspectives (design-time vs tenant-specific run-time metadata) +- Access strategies and governance aspects + +**Relationship to this SEP:** + +ORD **can** handle AI protocol discovery today, but due to enterprise requirements it is quite complex. +This proposal assumes that for the AI ecosystem a simpler approach is desired and more realistic. + +| Aspect | ORD | This SEP | +|--------|-----|----------| +| **Target Audience** | Enterprise IT, governance teams | AI developers | +| **Scope** | APIs, events, data products, taxonomy | AI protocols only (MCP, A2A) | +| **Complexity** | Comprehensive, extensive specification | Simple (5 required fields) | +| **Adoption Barrier** | High (complex data models) | Low (small JSON schema) | + +**Coexistence options:** +- **Enterprise environments**: Use ORD for comprehensive discovery +- **AI-focused environments**: Use lightweight `/.well-known/ai-cards.json` +- **Hybrid deployments**: Implement both as needed, only AI Card when describing pure Agents / MCP Servers. + +## Links + +- [Model Context Protocol (MCP)](https://modelcontextprotocol.io) - Protocol for connecting AI assistants to data sources and tools + - [MCP SEP-2127: Server Cards](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) - Proposed MCP Server Card format + - [MCP Registry](https://github.com/modelcontextprotocol/registry) - Existing registry format +- [Agent-to-Agent Protocol (A2A)](https://a2a-protocol.org) - Protocol for agent-to-agent communication + - [A2A Specification](https://a2a-protocol.org/latest/specification/) + - [A2A Well-Known URI Registration](https://github.com/protocol-registries/well-known-uris/issues/66) + +- Discovery protocols + - [RFC 9727: api-catalog](https://datatracker.ietf.org/doc/rfc9727/) - Generic API discovery (see Prior Art for detailed comparison) + - [Open Resource Discovery (ORD)](https://open-resource-discovery.org/spec-v1) - Enterprise-grade resource discovery (see Prior Art for detailed comparison) + - [Entity Discovery Protocol (EDP)](https://github.com/edp-protocol/entity-discovery-protocol) - Protocol for discovering business entities + +- Foundational standards + - [RFC 8615: Well-Known Uniform Resource Identifiers (URIs)](https://www.rfc-editor.org/rfc/rfc8615.html) - Foundation for .well-known URIs + - [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986) - URL resolution rules used in this specification