docs: add best practices for server and client implementors by tadasant · Pull Request #36 · modelcontextprotocol/ext-server-card · GitHub

Adds docs/best-practices.md and links it from the README. Docs-only; no schema or code changes.

The doc speaks for itself — read it here. This description covers only what it does not say about itself.

Why

The repo documents the mechanics of Server Cards but never says when to serve one, or what a client should do with one it finds. This fills that gap as advisory guidance layered on the normative material in the README, discovery.md, and the AI Catalog spec.

Positions worth reviewing explicitly

These are judgment calls, not obvious consequences of the spec. Argue with them here:

Default-on probing for user-entered URLs is stated as a floor for client implementors, with tool-call results and network egress explicitly recommended off by default until the pattern proves out. That's a recommendation this repo has not made before.
Installs are held to a stricter bar than tool calls — no autonomous installation.
Client examples are all Goose. One real AAIF maintained client, concretely, rather than only an abstraction over several

Relationship to other work

⚠️ Use AI Catalog for Server Card discovery #42 should merge first. This is a content dependency, not just a link check. docs/discovery.md on main still specifies the MCP Catalog at /.well-known/mcp/catalog.json; this doc tells implementors to publish and probe /.well-known/ai-catalog.json. Until Use AI Catalog for Server Card discovery #42 ("Use AI Catalog for Server Card discovery", Closes #26) lands, the two docs in docs/ disagree on the single most load-bearing URL. There is no textual conflict — this PR touches only docs/best-practices.md and README.md, and the anchors it uses survive Use AI Catalog for Server Card discovery #42 — but merging this first would ship an internally inconsistent docs/ directory.
Discovery: recommend ETag + conditional requests (If-None-Match/304) as a SHOULD for card/catalog endpoints #33 (ETag + conditional requests) is anticipated client-side without restating it normatively — that belongs in discovery.md if Discovery: recommend ETag + conditional requests (If-None-Match/304) as a SHOULD for card/catalog endpoints #33 lands.
Closes Add Best Practices for Client implementors #40.

Verification

npm run check, npm run validate, npm run format:check pass
Rebased onto current main; picks up the terminology change from docs: drop references to the MCP initialization handshake (SEP-2575) #37
Internal anchors resolve, and are checked against Use AI Catalog for Server Card discovery #42's post-merge headings
Field names checked against schema.ts / schema.json; remaining Goose citations re-verified against live docs (dead sandbox link dropped, AAIF attribution corrected)
No MCP-Catalog / well-known/mcp references introduced (grep-clean)
No changes outside docs/ and README.md

Adds docs/best-practices.md covering guidance for hosting Server Cards and for discovering/installing servers from an AI Catalog in-session.

Matches the shape of the client implementor section: an intro paragraph followed by ### subsections, rather than a flat bullet list.

Opens with why in-session discovery is worth building, states a default-on recommendation for user-entered URLs, and marks broader triggers (tool results, egress) as opt-in for now. Regroups the subsections into trigger points, install, and security, and adds flow diagrams for the recommended flow and the trigger spectrum.

- Remove the URL-scheme / install-link guidance as nonstandard - Add a minimal prompt mockup showing the endorsement chain - Require explicit approval for every install; offer session-scoped vs persistent accept instead of a blanket always-allow - Soften the catalog-culling advice to an invitation to experiment - Expand the enterprise path into a pre-filled request-to-IT flow

Each client mechanism now leads with the general shape any client can implement; Goose specifics follow in parentheses as one concrete instance. Drops the verbatim goose:// deep-link template.

- description is required, not optional; remove the auth field from the IT-request mock (no such field exists; issue #13 is v2) - Goose is AAIF-hosted, not Block's; drop the 404 sandbox link; hooks live in a plugin's hooks/hooks.json per the Open Plugins spec - Genericize the GitHub mockups to example.com / mcp-host-saas.com - Replace 'endorsement' with 'listing', and note the trust manifest is the spec's actual mechanism where present - Add probe bounds: no IP literals, loopback, link-local or private ranges; re-check after DNS; no ambient credentials; bound redirects - De-dup on the server endpoint rather than self-asserted name, and move the check after the card fetch - Note catalog nesting, depth cap and cycle tracking; note inline entries - Lowercase the invented MUST NOT; cut 'at someone else's development cost'

…ives The specification identifies a catalog by media type rather than path, and its discovery procedure checks a Link header and an HTML <link> element ahead of the well-known URI. Recommend .well-known as the primary location for both sides, and tell servers to advertise and clients to honor the other two. Cite ai-catalog.io/spec throughout.

Keeps the guidance to the one mechanism the extension implements today, worded so additional modes can be added without a rewrite.

Keeps the client flow to the flat catalog the extension resolves today, worded so entry handling can gain cases.

Pretty happy with this, will be great to get other eyes on it but I made a few comments.

Probably we want to gloss over it, but technically the AI Catalog is including static assets like STDIO MCP runtimes right?

I certainly remember being at a meeting where they discussed that.

Yeah, though it's a bit of an open question for me at the moment, so I wouldn't land it here yet

As you recently highlighted the well known mechanism is not the sole mechanism, and the <link rel="_ai_catalog \> was added since this was written.

That is what the linked #43 is about :)

Co-authored-by: Sam Morrow <sammorrowdrums@github.com>

Several paragraphs were left unwrapped while the rest of the file wraps at ~95 columns. Reflow them so the file is internally consistent. The only line still over 100 is an atomic markdown link that cannot be broken. Deliberately not adding a repo-wide prettier proseWrap setting here: it would reflow discovery.md, which PR #42 is actively rewriting.

What the client declines to recommend is a server, not a party.

The WG's proposed priorities for the core-maintainer roadmap, per the Jul 27 meeting. Three tracks, in priority order: 1. **Graduate the Server Card as an official MCP extension** — gated on merging an SDK reference impl (Python [python-sdk#2951], Go [go-sdk#1024], TS [typescript-sdk#2527]), landing best practices ([#40]/[#36]), and keeping the GitHub showcase ([#34]) in sync. 2. **Describe what a server does, not just where to reach it** — the primitives / static-capability work ([#30]), framed around the problem: a card lists URLs but no operations for consumers that never connect. 3. **Authentication** — express real-world per-remote auth ([#13]); land a limited shape first, expand as a fast-follow. Kept deliberately short as a strawman for public comment. Docs-only; `format:check` passes. [python-sdk#2951]: modelcontextprotocol/python-sdk#2951 [go-sdk#1024]: modelcontextprotocol/go-sdk#1024 [typescript-sdk#2527]: modelcontextprotocol/typescript-sdk#2527 [#13]: #13 [#30]: #30 [#34]: #34 [#40]: #40 [#36]: #36 --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 904e057e-7dd0-4dfc-9e15-571ddeb8475f Copilot-Session: 2eabcc66-5630-47ce-b193-171bbcaff1e8

tadasant marked this pull request as draft June 26, 2026 21:45

This was referenced Jul 2, 2026

docs: refactor MCP mapping appendix to Server Cards + align with MCP spec Agent-Card/ai-catalog#53

Merged

docs: add server.json as a first-class catalog type (application/mcp-server+json) Agent-Card/ai-catalog#54

Draft

tadasant mentioned this pull request Jul 13, 2026

Add Best Practices for Client implementors #40

Open

docs: add best practices for server and client implementors

472f446

Adds docs/best-practices.md covering guidance for hosting Server Cards and for discovering/installing servers from an AI Catalog in-session.

tadasant force-pushed the docs/best-practices branch from 3307923 to 472f446 Compare July 20, 2026 01:40

tadasant and others added 6 commits July 20, 2026 01:43

docs: restructure server implementor guidance into prose subsections

52126c3

Matches the shape of the client implementor section: an intro paragraph followed by ### subsections, rather than a flat bullet list.

Refinements

e6ee9b6

docs: demote Goose from framing device to illustration

de65e76

Each client mechanism now leads with the general shape any client can implement; Goose specifics follow in parentheses as one concrete instance. Drops the verbatim goose:// deep-link template.

YE-YI7 mentioned this pull request Jul 20, 2026

Reference implementation showcase: value/selection metadata riding AI Catalog metadata + Server Card _meta (live wire formats & routes) #41

Closed

tadasant added 2 commits July 20, 2026 15:26

docs: explain only .well-known, track other discovery modes in #43

b8b59eb

Keeps the guidance to the one mechanism the extension implements today, worded so additional modes can be added without a rewrite.

tadasant marked this pull request as ready for review July 20, 2026 15:31

tadasant requested review from SamMorrowDrums and dsp-ant July 20, 2026 15:44

docs: drop nested-catalog guidance, track in #44

78a4e5e

Keeps the client flow to the flat catalog the extension resolves today, worded so entry handling can gain cases.

SamMorrowDrums previously approved these changes Jul 20, 2026

View reviewed changes

This was referenced Jul 21, 2026

Add experimental Server Card extension support (SEP-2127) modelcontextprotocol/python-sdk#3139

Draft

Add experimental Server Card extension support (SEP-2127) modelcontextprotocol/typescript-sdk#2527

Draft

Update docs/best-practices.md

b5d16da

Co-authored-by: Sam Morrow <sammorrowdrums@github.com>

tadasant dismissed SamMorrowDrums’s stale review via b5d16da July 24, 2026 09:34

tadasant added 2 commits July 24, 2026 09:36

docs: 'recommending anything' over 'anyone'

1b06488

What the client declines to recommend is a server, not a party.

SamMorrowDrums mentioned this pull request Jul 27, 2026

docs: add Server Card roadmap priorities #47

Merged

+              If your server is **not remote**, there is nothing to serve a card for — Server Cards exist to
+              advertise remote transport endpoints only. Locally-installable server metadata lives in the
+              [MCP Registry](https://github.com/modelcontextprotocol/registry)'s `server.json` schema instead
+              (see [Relationship to the MCP Registry](../README.md#relationship-to-the-mcp-registry)).

+              **Serve it at `/.well-known/ai-catalog.json`.** That is the one location a client can try
+              against a bare domain, with nothing fetched from you first — which is exactly what in-session
+              discovery depends on. (The specification allows a catalog to live elsewhere, and defines other
+              ways to point at one; support for those is tracked in
+              [#43](https://github.com/modelcontextprotocol/experimental-ext-server-card/issues/43).)

docs: add best practices for server and client implementors by tadasant · Pull Request #36 · modelcontextprotocol/ext-server-card · GitHub

Uh oh!

docs: add best practices for server and client implementors - #36

docs: add best practices for server and client implementors#36
tadasant wants to merge 13 commits into
mainfrom
docs/best-practices

tadasant commented Jun 26, 2026 •
edited
Loading

Uh oh!

Uh oh!

SamMorrowDrums left a comment

Uh oh!

SamMorrowDrums Jul 20, 2026

Uh oh!

tadasant Jul 24, 2026

Uh oh!

SamMorrowDrums Jul 20, 2026

Uh oh!

tadasant Jul 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: add best practices for server and client implementors by tadasant · Pull Request #36 · modelcontextprotocol/ext-server-card · GitHub

Uh oh!

docs: add best practices for server and client implementors - #36

docs: add best practices for server and client implementors#36tadasant wants to merge 13 commits intomainmodelcontextprotocol/ext-server-card:mainfrom docs/best-practicesmodelcontextprotocol/ext-server-card:docs/best-practicesCopy head branch name to clipboard

Conversation

tadasant commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Positions worth reviewing explicitly

Relationship to other work

Verification

Uh oh!

SamMorrowDrums left a comment

Choose a reason for hiding this comment

Uh oh!

SamMorrowDrums Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

tadasant Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

SamMorrowDrums Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

tadasant Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: add best practices for server and client implementors#36
tadasant wants to merge 13 commits into
mainfrom
docs/best-practices

tadasant commented Jun 26, 2026 •
edited
Loading