docs: refactor MCP mapping appendix to Server Cards + align with MCP spec#53
Open
tadasant wants to merge 14 commits into
Open
docs: refactor MCP mapping appendix to Server Cards + align with MCP spec#53tadasant wants to merge 14 commits into
tadasant wants to merge 14 commits into
Conversation
Contributor
|
Preview: https://ai-catalog.io/pr/53/ This comment is updated automatically while the pull request preview is available. |
tadasant
changed the title
tadasant
changed the title
11 tasks
tadasant
added a commit
that referenced
this pull request
Jun 26, 2026
…pendix PR #53 alone does not add a server.json appendix (that lands in a stacked follow-up). Acknowledge server.json exists as a distinct artifact type without claiming this PR provides guidance on it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tadasant
pushed a commit
that referenced
this pull request
Jul 2, 2026
6 tasks
tadasant
pushed a commit
that referenced
this pull request
Jul 2, 2026
… ext-server-card PR #32 Reconcile the server.json mapping appendix with the current ADRs and the landing state of modelcontextprotocol/experimental-ext-server-card PR #32: - Fix the self-contradictory `type` note: examples for entries pointing at a Registry server.json now use the generic `application/json` (no known type exists for server.json), consistent with the note's own rationale. - Explain the open-text `type` model (ADR 0014) and the deliberate `application/mcp-server-card+json` vs `application/mcp-server+json` distinction (ext-server-card issue #9 / PR #18; PR #32 keeps the card value while renaming the field to `type`). - Correct SEP reference SEP-1649 -> SEP-2127 (heading, links, anchors). - Correct Server Card location prose: any unreserved URI, reserved default `<streamable-http-url>/server-card` (not `.well-known`). - Note the urn:air identifier form (ADR 0015) in the conceptual mapping. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Use anonymous.modelcontextprotocol.io publisher in the name-row example to match the brave-search entries rendered elsewhere in the appendix. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… server.json to experimental Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ith MCP spec - Remove the 'experimental' MCP Registry server.json mapping (server.json gets a first-class treatment in a follow-up PR). - Replace stale .well-known/mcp/server-card.json example URLs with the current <streamable-http-url>/server-card convention (the Server Card WG dropped the .well-known requirement for the card itself). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…pendix PR #53 alone does not add a server.json appendix (that lands in a stacked follow-up). Acknowledge server.json exists as a distinct artifact type without claiming this PR provides guidance on it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
MCP is removing the mandatory initialize handshake (modelcontextprotocol/ modelcontextprotocol#2575, stateless MCP). The Server Card description no longer frames itself as mirroring that handshake response; it simply states the fields the card carries. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The scope note called the card a 'runtime discovery document' while the Overview called it 'static'; align on 'static' (the SEP-2127 framing and the accurate one now that the card is the static replacement for the removed initialize handshake). The connection/runtime nuance stays in the parenthetical. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…g detail to SEP-2127 The overview repeated SEP-2127's precise hosting rule (reserved <streamable-http-url>/server-card default), which can drift from the SEP. Replace it with a high-level, example-led description and link out to SEP-2127 for the card's schema, fields, and hosting conventions. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ard examples version and description restate values the referenced Server Card already carries, the same drift risk that keeps displayName/title out of the entry. Drop them from the example entries and update the conceptual mapping table to justify the omission (as the title row already does), while keeping the mapping documented. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… points Replace the rigid 1-5 catalog-first ordering with a description that matches experimental-ext-server-card PR #36: the Server Card is a connection entry point useful on its own when the client already knows the URL, discovery has no single prescribed ordering, and the card is advisory (reconciled against the live connection, never authoritative for access control). Link out to the best-practices guidance.
… mapping The Server Card carries its own `repository` field, so copying it into entry `metadata.repository` duplicates a value that can drift — the same argument that keeps `title`/`description`/`version` in the card. Leave `repository` in the card; catalog-level provenance/source links belong in the Trust Manifest.
…ift fields A remote MCP server serves exactly one Server Card, so a catalog never lists multiple versions of it — the multi-version carve-out doesn't apply on the Server Card side. Drop it and treat `version` like the other drift-prone fields (stays in the card, omitted from the entry). The multi-version distinction remains on the server.json side (PR #54), where a registry genuinely can serve multiple versions.
…rd appendix Keep the Server-Card-only spec free of server.json references. The two-types naming rationale (application/mcp-server-card+json vs application/mcp-server+json) belongs with the server.json mapping, which is introduced in the stacked follow-up PR, not here.
tadasant
force-pushed
the
docs/update-server-json-mapping
branch
from
ceab926 to
e9a979f
Compare
tadasant
pushed a commit
that referenced
this pull request
Jul 2, 2026
…p-server+json) Stacked on #53. Reintroduces the MCP Registry server.json mapping that #53 removed, but as a first-class cataloged artifact type with its own known media type application/mcp-server+json (registered in ADR 0014 and the spec's known-types list), rather than an experimental footnote. Adds the 'Mapping to MCP Registry server.json' appendix: conceptual mapping table (with the same drift-avoidance omissions as the Server Card side, but retaining the multi-version version carve-out since a registry can serve multiple versions), an entry example and an 'MCP Registry as AI Catalog' example using real registry API URLs, and a 'Relationship to MCP Server Cards' two-types section.
The paragraph's first sentence duplicated the Overview immediately below it, and its second sentence referenced the MCP Registry server.json — which the Server-Card-only spec deliberately does not mention. The Server-Card-vs-server.json distinction lives in the stacked follow-up PR's dedicated 'Relationship to MCP Server Cards' section.
tadasant
pushed a commit
that referenced
this pull request
Jul 2, 2026
…p-server+json) Stacked on #53. Reintroduces the MCP Registry server.json mapping that #53 removed, as a first-class cataloged artifact type with its own known media type application/mcp-server+json (registered in ADR 0014 and the spec's known-types list). Adds the 'Mapping to MCP Registry server.json' appendix: conceptual mapping table (same drift-avoidance omissions as the Server Card side, but retaining the multi-version version carve-out since a registry can serve multiple versions), an entry example and an 'MCP Registry as AI Catalog' example using real registry API URLs, and a 'Relationship to MCP Server Cards' two-types section. Purely additive over #53 (no shared-prose edits).
tadasant
pushed a commit
that referenced
this pull request
Jul 2, 2026
…p-server+json) Stacked on #53. Reintroduces the MCP Registry server.json mapping that #53 removed, as a first-class cataloged artifact type with its own known media type application/mcp-server+json (registered in ADR 0014 and the spec's known-types list). Adds the 'Mapping to MCP Registry server.json' appendix: conceptual mapping table (same drift-avoidance omissions as the Server Card side, but retaining the multi-version version carve-out since a registry can serve multiple versions), an entry example and an 'MCP Registry as AI Catalog' example using real registry API URLs, and a 'Relationship to MCP Server Cards' two-types section. Purely additive over #53 (no shared-prose edits).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Refreshes the MCP mapping appendix of the spec (live: https://ai-catalog.io/#mapping-to-mcp-registry-server-json), which was very outdated, and does a broader clean-up pass to align the spec's MCP examples with the current MCP spec.
Scope note: server.json
The previous version of this appendix centered on the MCP Registry
server.jsonformat. That mapping is removed here; we will consider reintroducing it after discussing with the MCP community how we want to position that with respect to AI Catalog. This PR is intentionally Server-Card-only.