Skip to content

feat(schema): add Remote.extensionsInfo for server-level extension information - #55

Open
poita wants to merge 2 commits into
mainfrom
feat/remote-extensions
Open

poita wants to merge 2 commits into
mainfrom
feat/remote-extensions

Conversation

@poita

@poita poita commented Oct 26, 2026 •

Copy link
Copy Markdown

Summary

Adds an optional extensionsInfo map to Remote, 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 _meta key naming rules (e.g. io.modelcontextprotocol/events); values are objects whose contents are defined by each extension. The map shape matches ServerCapabilities.extensions, and JSONValue / JSONObject / JSONArray are inlined verbatim from the core schema alongside the existing inlined MetaObject and Icon.

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 via server/discover, which may vary per user. docs/discovery.md states 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-wg discussion 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:

ServerCard.remotes[x].extensionsInfo["io.modelcontextprotocol/events"].webhooks

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.json regenerated.
  • docs/discovery.md: clarify that extensionsInfo carries 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.
  • Examples: valid/remote-extensions-info.json (illustrative events/webhooks entry) and invalid/non-object-extension-info.json (entries must be objects).

Compatibility

Additive and optional; existing cards remain valid.

Note: the generated JSONValue (string | integer | boolean, no null) is identical to the core schema/draft/schema.json output from typescript-json-schema with --defaultNumberType integer; kept identical to core rather than diverging here.

Verification

  • npm run check — schema.json in sync, tsc passes
  • npm run validate — all 9 examples pass; the new invalid example was confirmed to be (wrongly) accepted before the schema change
  • npm run format:check

🤖 Generated with Claude Code

https://claude.ai/code/session_01BzSw9zenmbDjJXgmtp94Pv

…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
@poita
poita marked this pull request as ready for review October 26, 2026 10:49
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Updated (UTC)
❌ Deployment failed
View logs
ext-server-card 68751bc Nov 14 2026, 08:22 PM

@pja-ant
pja-ant requested a review from tadasant October 28, 2026 18:30
SamMorrowDrums
SamMorrowDrums previously approved these changes Nov 2, 2026

@SamMorrowDrums SamMorrowDrums left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@tadasant tadasant left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can discuss if this is problematic feedback for you @poita - but I think it would be cleaner to call this something like extensionsInfo?

Other comments are just keeping some consistency with our posture on "security metadata".

Comment thread schema.ts Outdated
* Keys MUST follow the {@link MetaObject | `_meta` key naming rules}, with a
* mandatory prefix.
*/
extensions?: { [key: string]: JSONObject };

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"],

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"supportedProtocolVersions": ["2025-11-25"],
"supportedProtocolVersions": ["2026-07-28"],

[nit] protocol version that has serverCapabilities.extensions

Comment thread docs/discovery.md
Comment on lines 162 to 169
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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread docs/discovery.md Outdated
Comment on lines +156 to +161
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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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
@poita poita changed the title feat(schema): add Remote.extensions for server-level extension information feat(schema): add Remote.extensionsInfo for server-level extension information Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants