[Proposal]: AI Open Discovery via API Catalog (RFC 9727 / RFC 9264)

[ognis1205]

[Proposal] AI Open Discovery via RFC 9264 / RFC 9727 API Catalog

Problem Statement

Many AI deployments expose multiple AI-related assets under a single origin, such as:

• Multiple A2A agents under /a2a/v1/*
• One or more MCP servers under /mcp/v1/*
• Other AI service endpoints

While each asset may expose its own metadata document, e.g. A2A Agent Card or MCP Server Card, there is currently **no standardized, open discovery mechanism **that allows a client to enumerate all AI assets available from a given origin.

---

Proposed Solution

This issue proposes adopting an API Catalog–based open discovery layer for AI-related assets, leveraging existing IETF standards:

• api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs
• Linkset: Media Types and a Link Relation Type for Link Sets

An origin MAY expose an API Catalog at the well-known location:

/.well-known/api-catalog

The catalog enumerates AI assets using Linkset entries, where each entry MAY include:

• An optional anchor representing the base URI of an AI asset
• One or more link relations pointing to asset-specific metadata documents,
  such as:
  • A2A Agent Cards
  • MCP Server Cards
  • Future AI Card–style documents

This provides a protocol-agnostic, extensible discovery mechanism without introducing new discovery formats.

---

Example AI API Catalog

{
  "linkset": [
    {
      "anchor": "https://ai.example.com/a2a/v1/route_planner",
      "describedby": [
        {
          "href": "https://ai.example.com/a2a/v1/route_planner/agent-card.json",
          "type": "application/agent-card+json",
          "title": "GeoSpatial Route Planner Agent (A2A)"
        }
      ]
    },
    {
      "anchor": "https://ai.example.com/mcp/v1/geocoding",
      "https://modelcontextprotocol.io/specification/#server-card": [
        {
          "href": "https://ai.example.com/mcp/v1/geocoding/mcp-card.json",
          "type": "application/json",
          "title": "GeoSpatial Reverse Geocoding Server (MCP)"
        }
      ]
    }
  ]
}

---

Relationship to AI Cards

This proposal intentionally keeps the discovery layer minimal.

• The API Catalog is used only for enumeration and linking
• Rich AI metadata is delegated to external documents such as:
  • A2A Agent Cards
  • MCP Server Cards

In the future, it may be desirable to define a more general AI Card that can subsume or reference existing card formats. Such a specification could naturally live in this repository, while remaining discoverable via the API Catalog mechanism described here.

---

Pros

• Protocol-agnostic discovery
  The API Catalog provides a neutral discovery layer
  that works across AI protocols such as A2A, MCP, and future AI-specific interfaces, without requiring
  protocol-specific discovery mechanisms.

• Standardized and interoperable
  By reusing existing IETF standards (RFC 9727),
  this approach avoids introducing new discovery formats and benefits from well-defined semantics,
  existing tooling, and prior operational experience.

• Supports multi-asset deployments
  Unlike single-resource discovery mechanisms (for example, one Agent Card per origin),
  the catalog naturally supports hosting and enumerating multiple AI assets under a shared origin
  or gateway.

• Extensible without central coordination
  New AI asset types, metadata formats, or relation types can be added incrementally using URI-based
  link relations, without requiring new global registries or schema changes.

---

Cons / Open Questions

• Not AI-specific by design
  The API Catalog was designed for general APIs, not AI
  assets specifically. Some AI-specific concepts may require additional conventions or profiles.

• Risk of inconsistent conventions
  Without additional guidance, different implementations may choose different anchor semantics, or
  relation types, which could reduce interoperability across catalogs. This could be improved through
  further discussion and consensus, for example by recommending specific relation types and stable
  schema URIs for assets such as the A2A Agent Card and the MCP Server Card.

• Limited expressiveness for rich metadata
  The catalog primarily supports discovery and linking. Rich AI metadata must be defined in external
  documents such as A2A Agent Cards or MCP Server Cards. A more general or unifying AI Card
  specification could be discussed and developed separately within this repository in the future.

---

Related Work

• A2A Project – [Feat]: Support multi-agent open discovery under a single base URL via RFC 9264-compatible API Catalog
• api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs
• Linkset: Media Types and a Link Relation Type for Link Sets