Skip to content

Discovery: consider GET-on-server-URL instead of (or alongside) .well-known for single-server cards #12

Closed

Description

@tadasant

Summary

Server Card discovery is currently specified as a static document served from a .well-known path (/.well-known/mcp/server-card). This issue argues we should seriously consider not using .well-known at all for the single-server case, and instead let ai-catalog.json (or temporarily mcp/catalog.json) point to a (non-.well-known) URI containing the Server Card.

This is largely inspired by @darrelmiller's points here.

What's specified today

SEP-2127 currently puts the card at a .well-known URI (seps/2127-mcp-server-cards.md#L257-L274, PR #2127):

Servers using HTTP-based transports SHOULD provide their server card at:

    /.well-known/mcp/server-card

…and schema.ts documents the same (schema.ts#L13-L14):

 * A static metadata document describing a remote MCP server, suitable for
 * publishing at a `.well-known/mcp/server-card` URI for pre-connection discovery.

The argument

The key point, borrowing from @darrelmiller:

The use of .well-known for discovering applications like MCP Servers and A2A agents that are hosted on some origin is a misuse of .well-known, because applications are not "site-wide metadata".

AI Catalog/MCP Catalog is responsible for initial discovery. So there is no value in using the .well-known standard for placing the final Server Card; an MCP client only needs to be aware of the Catalog's .well-known URI and the Server Card URI can live anywhere.

Proposed resolution

@SamMorrowDrums and I are thinking some spec wording roughly like so:

In the course of Discovery, after an MCP Client identifies a Server Card URL from an AI Catalog or MCP Catalog, MCP Clients SHOULD set Content-Type to `application/mcp-server-card+json` when performing a GET request to the Server Card's URL.

MCP Servers MAY host their Server Card at `GET <streamable http url>/server-card`, which we reserve for this purpose, though any unreserved URI is valid. MCP Servers SHOULD respect Content-Type `application/mcp-server-card+json` wherever they choose to host it.

Alternative guidance considered: GET directly on <streamable http url>. Choosing not to recommend this just to avoid overloading that endpoint that is already used for establishing the SSE connection, but it would technically be spec-compliant (as written above) to put it there as well.

Activity

  1. tadasant commented on Jun 1, 2026

    @tadasant
    MemberAuthor

    @SamMorrowDrums and I think using .well-known here is a legacy decision back from when we thought Server Card would also be the discovery entrypoint, and also back when we made the decision to not allow reverse-engineering the location of a Server Card based on the reverse DNS name (i.e. com.example/my-mcp would have its Card at example.com/mcp/server-card/my-mcp -- we don't want this because that tightly couples name to this unintuitive reverse engineering).

    References:

  2. self-assigned this
    on Jun 1, 2026
  3. added a commit that references this issue on Jun 8, 2026
    96aa564
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

sep-2127-blockersMust be resolved before SEP-2127 can be ratified/advanced

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions