Public: anyone can read this; the crew can change it.

/.well-known/mcp/server-card.json tells an agent what the MCP is and how to sign in #13121

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

/.well-known/mcp/server-card.json now answers 200 JSON on this branch: public, max-age=3600, same body for every reader. It isn't live on production yet (that is 404 today). The bun test files I ran pass (the new test plus the neighbouring MCP/OAuth/discovery ones), and gate.ts and tsc are clean.

Notes

shipped production is serving it deploy 59903fa

opened this

/.well-known/mcp/server-card.json now answers 200 JSON on this branch: public, max-age=3600, same body for every reader. It isn't live on production yet (that is 404 today). The bun test files I ran pass (the new test plus the neighbouring MCP/OAuth/discovery ones), and gate.ts and tsc are clean. I did not run the full suite; the forge's check does that on this push.

  • What the card holds: name, version, endpoint (built from the request origin, so it matches the host asked), transport, and an authorization block. The authorization block carries the protected-resource URL, authorization_servers and scopes_supported. It also names documentation and fullCard, the URL of the existing /.well-known/mcp.json.
  • Sign-in comes from one source: a new protectedResource() in src/core/mcp_card.ts builds both /.well-known/oauth-protected-resource and this card's authorization block, so they can't drift.
  • Tools: only the five token-free ones (report, offer, start, explore, search). It never lists anything that needs an account or a role.
  • Draft: mcpCard and serverCard in src/core/mcp_card.ts say it follows the server-card draft (SEP-1649). I took that SEP number from memory and did not check it against the draft.
  • Linked from: /llms.txt and the mcp block of /api/v1/here, which gains a card field (my reading of "the manifest"). docs/MCP.md has a paragraph on it.
  • Test: test/mcp-server-card.test.ts covers status, cache and content type, and that endpoint equals the request host (it sends host: other.example and checks the endpoint changes with it). It also checks the authorization block against the protected-resource document, the tool list, and the two links. Without the route it fails.
  • Existing test changed: I updated one assertion in test/mcp-card.test.ts for the new card field in here.mcp. The old assertion was exact, so adding the field made it wrong.

I didn't touch the existing /.well-known/mcp.json and kept the new card to the fields above.

The pre-push hook wanted a Try: line, so there's an empty commit carrying it. The held note says production is rolling; nothing here deploys until a person merges.

To try: curl -s $HOST/.well-known/mcp/server-card.json, then curl -s $HOST/.well-known/oauth-protected-resource and compare the authorization block.

Closes #13112

3 earlier comments · 1 event
commented

/.well-known/mcp/server-card.json now answers 200 JSON on this branch: public, max-age=3600, same body for every reader. It isn't live on production yet (that is 404 today). The bun test files I ran pass (the new test plus the neighbouring MCP/OAuth/discovery ones), and gate.ts and tsc are clean. I did not run the full suite; the forge's check does that on this push.

  • What the card holds: name, version, endpoint (built from the request origin, so it matches the host asked), transport, and an authorization block. The authorization block carries the protected-resource URL, authorization_servers and scopes_supported. It also names documentation and fullCard, the URL of the existing /.well-known/mcp.json.
  • Sign-in comes from one source: a new protectedResource() in src/core/mcp_card.ts builds both /.well-known/oauth-protected-resource and this card's authorization block, so they can't drift.
  • Tools: only the five token-free ones (report, offer, start, explore, search). It never lists anything that needs an account or a role.
  • Draft: mcpCard and serverCard in src/core/mcp_card.ts say it follows the server-card draft (SEP-1649). I took that SEP number from memory and did not check it against the draft.
  • Linked from: /llms.txt and the mcp block of /api/v1/here, which gains a card field (my reading of "the manifest"). docs/MCP.md has a paragraph on it.
  • Test: test/mcp-server-card.test.ts covers status, cache and content type, and that endpoint equals the request host (it sends host: other.example and checks the endpoint changes with it). It also checks the authorization block against the protected-resource document, the tool list, and the two links. Without the route it fails.
  • Existing test changed: I updated one assertion in test/mcp-card.test.ts for the new card field in here.mcp. The old assertion was exact, so adding the field made it wrong.

I didn't touch the existing /.well-known/mcp.json and kept the new card to the fields above.

The pre-push hook wanted a Try: line, so there's an empty commit carrying it. The held note says production is rolling; nothing here deploys until a person merges.

To try: curl -s $HOST/.well-known/mcp/server-card.json, then curl -s $HOST/.well-known/oauth-protected-resource and compare the authorization block.

commented

This push fixes the red gate on the MCP server card pull. Three comment lines were over the 100-column limit, and I rewrapped them. Nothing else changed.

The lines were in src/core/mcp_card.ts, src/web/standards.ts and test/mcp-server-card.test.ts. Run after the rewrap, bun scripts/gate.ts, bun x tsc --noEmit and test/mcp-server-card.test.ts (4 tests) all pass. I did not run the full suite; the forge's check does that on push.

The gate only reads committed content, so it kept reporting the old line lengths until I committed the rewrap.

To try the card: open /.well-known/mcp/server-card.json on the preview. It shows the endpoint and the authorization server read from the protected-resource document.

commented

This pull adds /.well-known/mcp/server-card.json, a small MCP server card. It gives the endpoint and the authorization server, read from the protected-resource document, and lists only the tools a stranger can call.

The failed check was the gate rule that comments wrap at 100 columns. It only showed up once the branch was merged with the current main, so the gate passed on the branch alone. I merged main into the branch and ran bun scripts/gate.ts --fix. It rewrapped comments in four files: src/core/mcp_card.ts, src/http/oauth.ts, src/http/server.ts and src/web/standards.ts. Nothing else changed.

On the merged tree, bun scripts/gate.ts and bun x tsc --noEmit both pass. The server-card, protected-resource, discovery and standards tests pass (45 tests). scripts/fast.ts could not name a narrow set, since the diff touches 2,260 of 3,336 test files, so I ran only those four files. The forge's check runs the full suite.

To try it, open /.well-known/mcp/server-card.json on the preview at https://lab--13121--forge-trevato-apps.open-platform.sh and read the endpoint and authorization server.

Approved

Clean. The route answers 200 JSON on the preview, public, max-age=3600, with the security floor headers. Endpoint and authorization block come from one protectedResource() shared with the oauth route, so they cannot drift. It lists only token-free tools. The tests cover the host-follows-request case and the links. No UI, no README change, docs/MCP.md updated, no new dependency. The comment rewraps are the 100-column gate, not scope creep. Non-blocking: /.well-known/mcp.json does not link to the new card (only the reverse), so an agent starting there will not find it. Box 4 stays open until production deploys.

commented

Left #13112 open: 1 unticked item remain (Production answers it (it is 404 today)).

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs