docs: add best practices for server and client implementors#36
Open
tadasant wants to merge 13 commits into
Open
docs: add best practices for server and client implementors#36tadasant wants to merge 13 commits into
tadasant wants to merge 13 commits into
Conversation
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
July 20, 2026 01:40
3307923 to
472f446
Compare
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'
added 2 commits
July 20, 2026 15:26
…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.
tadasant
marked this pull request as ready for review
July 20, 2026 15:31
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
SamMorrowDrums
left a comment
SamMorrowDrums
left a comment
Collaborator
There was a problem hiding this comment.
Pretty happy with this, will be great to get other eyes on it but I made a few comments.
Comment on lines
+39
to
+42
| 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)). |
Collaborator
There was a problem hiding this comment.
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.
Member
Author
There was a problem hiding this comment.
Yeah, though it's a bit of an open question for me at the moment, so I wouldn't land it here yet
Comment on lines
+55
to
+59
| **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).) |
Collaborator
There was a problem hiding this comment.
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.
Co-authored-by: Sam Morrow <[email protected]>
added 2 commits
July 24, 2026 09:36
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.
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
2 participants
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.
Adds
docs/best-practices.mdand 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:
Relationship to other work
docs/discovery.mdonmainstill 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 indocs/disagree on the single most load-bearing URL. There is no textual conflict — this PR touches onlydocs/best-practices.mdandREADME.md, and the anchors it uses survive Use AI Catalog for Server Card discovery #42 — but merging this first would ship an internally inconsistentdocs/directory.discovery.mdif Discovery: recommend ETag + conditional requests (If-None-Match/304) as a SHOULD for card/catalog endpoints #33 lands.Verification
npm run check,npm run validate,npm run format:checkpassmain; picks up the terminology change from docs: drop references to the MCP initialization handshake (SEP-2575) #37schema.ts/schema.json; remaining Goose citations re-verified against live docs (dead sandbox link dropped, AAIF attribution corrected)well-known/mcpreferences introduced (grep-clean)docs/andREADME.md