Negotiating Capabilities

MCP is rich, but no client or server supports it all. So at startup both sides negotiate which features they have, like two devices agreeing on what they can do. 🤝

This deal is struck during the initialize handshake, the very first exchange. After it, each side knows what the other offers and what is off the table.

The client announces its clientCapabilities and the server announces its serverCapabilities. Each bundle is just a map of feature flags and small options.

A server lists what it provides: things like tools, resources, and prompts. If a key is absent, clients know not to expect that primitive from you.

A client lists features it can offer back, such as roots, sampling, and elicitation. That is how your server learns it may even ask for roots at all.

A capability can hold extra options. For example, roots may carry listChanged: true, meaning the client will notify you when its root set changes.

The rule is simple: if a capability is missing, treat the feature as unavailable. Never call something the other side never promised it could do.

Alongside features, both sides send a protocolVersion. They must agree on a shared version, or the session is rejected before any real work begins.

You rarely build these maps by hand. The Python SDK fills in your server capabilities from the tools and resources you registered, then exchanges them for you.

After init, you can inspect the client capabilities your session captured. That check is exactly what guards an optional call like list_roots.

Capabilities are settled at startup and hold for the session. You can rely on them for the connection's life without re-negotiating on every call.

Recall when and how features get agreed on.

At initialize, client and server swap capability maps and a protocol version. A missing flag means unsupported, and the SDK builds and reads these for you. 🎯