Repository navigation
Conversation
…ation Gives MCP extensions a place on each remote to publish information a client needs before connecting (e.g. webhook signing keys for SEP-3415 Events). Entries are not a declaration of extension support; support is negotiated via server/discover. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BzSw9zenmbDjJXgmtp94Pv
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
ext-server-card | 68751bc | Nov 14 2026, 08:22 PM |
SamMorrowDrums
left a comment
There was a problem hiding this comment.
The example is certainly very specific, but at the same time it does sufficiently explain why this is useful and not just gloss.
My only mild hesitation is that a server card can be hosted separately to a server, and it's possible to publish a server card for somebody else's server.
| * Keys MUST follow the {@link MetaObject | `_meta` key naming rules}, with a | ||
| * mandatory prefix. | ||
| */ | ||
| extensions?: { [key: string]: JSONObject }; |
There was a problem hiding this comment.
A concern I have about the key name being extensions is that we're very likely to want to add a discoverable list of capabilities (and thus capabilities.extensions) to Server Card (issue here). If we keep this as remote.extensions, it may be confusing to see it near remote.capabilities.extensions.
Could we change this to something like extensionsMetadata or extensionsInfo?
| { | ||
| "type": "streamable-http", | ||
| "url": "https://mcp.example.com/mcp", | ||
| "supportedProtocolVersions": ["2025-11-25"], |
There was a problem hiding this comment.
| "supportedProtocolVersions": ["2025-11-25"], | |
| "supportedProtocolVersions": ["2026-07-28"], |
[nit] protocol version that has serverCapabilities.extensions
| As with the deliberately omitted primitives (tools, resources, prompts), a static manifest | ||
| can drift from runtime, so even the fields a Server Card does declare are advisory rather | ||
| than binding. Accordingly: | ||
|
|
||
| - Clients MUST NOT treat Server Card contents as authoritative for security or | ||
| access-control decisions. | ||
| - Clients SHOULD verify a Server Card's claims against the live connection, preferring the | ||
| runtime values where the two disagree. |
There was a problem hiding this comment.
| As with the deliberately omitted primitives (tools, resources, prompts), a static manifest | |
| can drift from runtime, so any such runtime-related fields a Server Card does declare are advisory rather | |
| than binding. Accordingly: | |
| - Clients MUST NOT treat Server Card contents as authoritative for security or | |
| access-control decisions that hold their source of truth at runtime | |
| - Clients SHOULD verify a Server Card's claims against the live connection, preferring the runtime values where the two disagree. | |
| For concerns that do not have a runtime equivalent, these caveats do not apply. |
We'll need to soften this MUST NOT, as this specific example is explicitly a security decision. I think that is fine to do - this clause was originally written from the perspective that runtime data can drift from the static Server Card, but in this case there is no possibility of more-authoritative runtime data that can disagree and so it's reasonable to allow this and be less absolute here.
| A remote's `extensions` map carries server-level information defined by each extension; it | ||
| is not a declaration of extension support. Clients MUST NOT infer from the presence or | ||
| absence of an entry whether the server supports that extension — support is negotiated via | ||
| `capabilities.extensions` in `server/discover`, which may vary per user and need not match | ||
| the Server Card. | ||
|
|
There was a problem hiding this comment.
| A remote's `extensions` map carries server-level information defined by each extension; it | |
| is not a declaration of extension support. Clients MUST NOT infer from the presence or | |
| absence of an entry whether the server supports that extension — support is negotiated via | |
| `capabilities.extensions` in `server/discover`, which may vary per user and need not match | |
| the Server Card. | |
| A remote's `extensions` map carries server-level information defined by each extension; it | |
| is not a declaration of extension support. Clients MUST NOT infer from the presence or | |
| absence of an entry whether the server supports that extension — support is negotiated via | |
| `capabilities.extensions` in `server/discover`, which may vary per user and need not match | |
| the Server Card. | |
| Extension information that a client relies on for a security decision (for example, verification keys or source IP ranges) MUST only be used when the Server Card was retrieved over HTTPS from the same origin as that remote's `url` (after variable substitution). Clients MUST NOT rely on such information from a Server Card hosted on another origin or embedded inline in a catalog entry. | |
To @SamMorrowDrums's point that a card can be hosted separately from the server, or published by someone else entirely: I think that stays fine for everything in the card today, because the live connection can contradict it. It's different for content like signing keys because there is nothing at runtime to check them against.
SEP-3415 already handles this dynamic for its case ("The verifying public key MUST be discovered from an origin the client already authenticates" and "The gateway fetches the card from the same origin it connects to for MCP"). We could mirror that for now, maybe there's some integration we could figure out with AI Catalog's mechanisms for carrying around trust later on.
That keeps "host a card anywhere" valid for discovery while making a third-party card incapable of spoofing keys.
…eats - Rename the map to extensionsInfo so it cannot be confused with a future capabilities.extensions on the card. - Security-relevant extension information is only usable from a card fetched over HTTPS from the remote's own origin, without cross-origin redirects. - The advisory caveats apply to fields the live connection can contradict. - The example declares protocol version 2026-07-28. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UMsZi9wRHH7j882xfkqw3y
Summary
Adds an optional
extensionsInfomap toRemote, giving MCP extensions a place to publish server-level information in the Server Card — data a client needs before any session exists.Keys are extension identifiers following the
_metakey naming rules (e.g.io.modelcontextprotocol/events); values are objects whose contents are defined by each extension. The map shape matchesServerCapabilities.extensions, andJSONValue/JSONObject/JSONArrayare inlined verbatim from the core schema alongside the existing inlinedMetaObjectandIcon.This is not a declaration of extension support. The presence or absence of an entry says nothing about whether the server supports that extension, and an entry need not match
capabilities.extensions. Support is negotiated viaserver/discover, which may vary per user.docs/discovery.mdstates this normatively (clients MUST NOT infer support from the card). It also requires that security-relevant extension information, such as verification keys, is only used from a card fetched over HTTPS from the remote's own origin, and scopes the existing advisory caveats to fields the live connection can contradict.Motivation
From the
tasks-events-wgdiscussion of SEP-3415 (Events): webhook receivers need the server's ed25519 signing keys (a JWK set) and, optionally, egress IP ranges from an origin they already trust. The agreed home is:This PR only adds the generic container; the contents of each entry are defined by the extension itself (SEP-3415 for events).
Changes
schema.ts:Remote.extensionsInfo?: { [key: string]: JSONObject }, plus inlined JSON types;schema.jsonregenerated.docs/discovery.md: clarify thatextensionsInfocarries extension-defined information, not support, and that clients MUST NOT infer support from it.README.md: mention server-level extension information in the remote-endpoint bullet.valid/remote-extensions-info.json(illustrative events/webhooks entry) andinvalid/non-object-extension-info.json(entries must be objects).Compatibility
Additive and optional; existing cards remain valid.
Note: the generated
JSONValue(string | integer | boolean, nonull) is identical to the coreschema/draft/schema.jsonoutput fromtypescript-json-schemawith--defaultNumberType integer; kept identical to core rather than diverging here.Verification
npm run check— schema.json in sync,tscpassesnpm run validate— all 9 examples pass; the new invalid example was confirmed to be (wrongly) accepted before the schema changenpm run format:check🤖 Generated with Claude Code
https://claude.ai/code/session_01BzSw9zenmbDjJXgmtp94Pv