CORE GUIDE
MCP capability negotiation
Capability negotiation lets an MCP client expose only the features and operations that both sides support and the current task is allowed to use, rather than assuming every available capability is active.
Mental model
Negotiation is a compatibility and policy handshake: discover what exists, intersect it with client support and application authorization, then establish the effective capability set for this session or task.
Why it matters
External capability surfaces evolve. Servers add tools, protocol features change, and different clients implement different subsets. If applications assume a fixed capability universe, upgrades can cause silent failure or accidental overexposure. Negotiation makes capability drift observable and gives the runtime a place to fail closed.
01
Derive the effective capability set explicitly
At connection or task start, read the server's advertised capabilities, compare them with the client's supported protocol features and the application's allowlist, then materialize the effective set. Require explicit handling for missing required capabilities and for newly advertised sensitive ones. Persist the negotiated version and set in traces for reproducibility.
02
Example: server upgrade adds a powerful write capability
After an MCP server upgrade, a new delete_project tool appears. A naive client exposes it immediately because discovery succeeded. A negotiated client intersects server capabilities with an application allowlist, so the new tool remains unavailable until policy and approval flows are deliberately updated.
Common failure modes
- Equating server-advertised capabilities with effective allowed capabilities.
- Failing open when a required capability or protocol feature is missing.
- Ignoring negotiated capability versions in traces and incident diagnosis.
Engineering heuristics
- Compute an explicit intersection of server, client and policy capabilities.
- Fail closed for missing requirements and newly sensitive operations.
- Trace the negotiated set so behavior can be reproduced after upgrades.
Takeaways
- 01Negotiation makes capability drift explicit.
- 02Available does not mean supported, and supported does not mean authorized.
- 03A reproducible session should record its effective capability set.
Reading evidence
This records actions you actually took; it does not claim mastery, proficiency, or certification.
Used in
This Concept is reused across these canonical learning paths.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.