SEP-2127: Remove primitives from server cards#2336
Conversation
Server cards should focus on identity, transport, and capability discovery. Primitive definitions (tools, resources, prompts) are removed because MCP servers are inherently dynamic — primitives vary by auth scope, feature flags, configuration, deployment state, session state, and more. A static manifest cannot reliably represent this dynamic surface. The 'dynamic' escape hatch acknowledged the problem but did not solve it. Until the protocol provides a mechanism for clients to understand which primitive surface applies to their context (e.g. server variants), server cards should not include information that cannot be reliably interpreted. Primitives remain discoverable through the protocol's standard list operations after connection establishment. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Clarify that including primitives in server cards risks creating a structural bias toward static servers, penalising servers that are dynamic for legitimate reasons. Call for a follow-on SEP to address prerequisites (variant enumeration, auth-scope signalling, partial listing contracts) before primitives are added. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add three further arguments for excluding primitives: - Deployment is not atomic: rolling deploys make server cards transiently wrong even for nominally static servers. - No substitute for runtime listing: only the protocol's list operations reflect the actual surface for the authenticated user. - Cache-invalidation analogy: a server card with primitives is an incoherent cache with no invalidation signal, and introducing caches without invalidation strategies is a well-known source of subtle distributed-systems bugs. - If primitives are ever reintroduced they must be treated as documentation-only, never for caching or signatures. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Server cards without primitives already enable the core use cases: autoconfiguration, domain-level discovery, reduced-latency metadata, and registry integration. Primitives can follow in a future revision once the ecosystem has the right mechanisms. Shipping discovery now and correctly is more important than shipping a larger surface that risks being wrong. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The detailed arguments belong in the PR discussion, not the spec itself. The SEP now states the position concisely and defers the full reasoning to the PR body. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
SamMorrowDrums
requested review from
dsp and
tadasant
and removed request for
dsp
tadasant
left a comment
tadasant
left a comment
There was a problem hiding this comment.
I'm on board with deferring this; tricky topic we should collect feedback on from a variety of folks and shouldn't block the discovery work.
- Remove 'full server surface' phrasing from design philosophy - Soften MUST to SHOULD for primitive discovery after connection Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
@tadasant agreed on changes. I don't know if we want to wait for Monday meeting before merge for quick consensus check? I don't have permission to do so at any rate, so I defer to you and David. |
Let's do it Monday; I don't have the permissions either. |
dsp
merged commit ea4ffd3
into
modelcontextprotocol:sep/mcp-server-cards
|
Sorry, I wasn't paying attention to all the changes / discussions in the meantime, but if we now remove the primitives, we have no static metadata description of the MCP Service anymore. Of course, the actual list of tools is dynamic and depends on the user / roles etc. - but sometimes you need to understand the server before you have that access, or independent of a particular user / role, e.g. to generate documentation, generate clients. E.g. compare this to OpenAPI, it also lists all operations, even though a particular user / role would not have access to all of them. With this change, it would make the MCP Server Card unfit for those purposes. Would then there be any alternative to describe the MCP Server statically? |
|
@Fannon we are open to discussing this, it is not a closed discussion. It's not quite as simple as the Open API example, because it's not limited to permissions, but content might even change depending on available tools (simple example is server instructions that are only relevant where combinations of tools are available). The core reason for this decision was to unblock discovery for now, ultimately a weak contract providing "roughly what the server contains" might be fine if it's understood to be a weak contract, and not abused for enforcement. |
|
@SamMorrowDrums - yes, I understand that list of tools can be dynamic. Actually at my company, same is true for REST APIs and OpenAPI, too. In a static metadata, you can only describe what you know at design-time. But at run-time the APIs can change due to config, extensions, customizations. And what's really available then depends on user-context and permissions. In my understanding MCP is not different than any other API protocol out there. But that it can exchange this information at runtime via the protocol standards itself is nice. Yes, it would be a "weaker contract", basically what you can know at that point in time. Only what you get back at runtime is then the reality. But usually this is a compatible subset/superset of the design-time contract. |
|
I don't disagree, |
5 participants
Summary
This PR removes primitive definitions (tools, resources, prompts) from the MCP Server Cards SEP, making server cards focused on identity, transport, capability, and authentication discovery.
Why remove primitives?
MCP servers are inherently dynamic. The primitives a server exposes can vary by authenticated user, session, configuration, feature flags, deployment state, and more. A static document cannot reliably represent this surface.
Key concerns with including primitives in a pre-connection document:
tools/list,resources/list, andprompts/listwith the logged-in user's identity produce correct results. A static manifest cannot know the user's OAuth scopes, subscription tier, feature-flag cohort, or which deployment version they will reach.Until proposals like Server Variants (SEP-2053) provide a mechanism for clients to understand which primitive surface applies to their context, server cards should be conservative.
Discovery should not wait
The primitives debate should not delay server card adoption. Discovery (where to connect, what transports are available, what auth is required) is enormously valuable on its own. It is the information an end user or IDE needs to install a server, and the information a registry needs to index one. None of this depends on knowing the tool list in advance.
What changed (13 insertions, 96 deletions)
resources,tools,promptsfields from schema and examplesEverything else is preserved: identity, transport, capabilities, auth,
server.jsonalignment,.well-knownendpoints, CORS, caching, IETF registration.