Discovery, capabilities and the two eras

Capabilities: say what you can do

Capabilities are how each side says which optional features it supports. It's like telling a caller that your phone can't receive photos, so they don't send one.

• Servers list tools, resources and prompts. Each may add details, such as listChanged, which means the server can announce when its list changes.
• Clients list features such as elicitation, which means the server may ask the user a question mid-call.
• Both may list extensions: optional add-ons named like io.modelcontextprotocol/tasks.

Because every request carries the client's capabilities, a server knows on each call what it may do. The rule is strict. A server must never rely on a capability the client didn't declare. If a request can't be done without one, the server answers MissingRequiredClientCapability, error code -32021, saying which capabilities it needed:

{"jsonrpc": "2.0", "id": 5, "error": {"code": -32021, "message": "confirm_order needs elicitation",
  "data": {"requiredCapabilities": {"elicitation": {}}}}}

The client can then decide: add the capability if it has it, or tell the user that this tool needs a feature their app lacks. An empty clientCapabilities of {} is valid. It means "only the basics", and it keeps simple scripts simple.

In plain words: each side declares what it can do, and nobody uses a feature the other side didn't declare.

PV = "io.modelcontextprotocol/protocolVersion"
CAPS = "io.modelcontextprotocol/clientCapabilities"

def needs(meta, *names):
    """The capabilities a request lacks, so the server can refuse before it starts."""
    declared = meta.get(CAPS, {})
    return [n for n in names if n not in declared]

plain = {PV: "2026-07-28", CAPS: {}}
rich = {PV: "2026-07-28", CAPS: {"elicitation": {}, "extensions": {"io.modelcontextprotocol/tasks": {}}}}

for label, meta in [("plain client", plain), ("rich client", rich)]:
    missing = needs(meta, "elicitation")
    if missing:
        print(label, "-> error -32021, requiredCapabilities:", {m: {} for m in missing})
    else:
        print(label, "-> ask the user, then confirm")

Living with two eras

New software must still talk to old software. Think of a bilingual receptionist who answers each caller in whichever language they open with. The spec defines dual-era clients and servers that speak both styles.

A dual-era server looks at how each request opens. An initialize request gets the legacy handshake. A request carrying modern _meta is served statelessly. The same server does both.

A dual-era client has to find out which kind of server it's facing. On stdio, it sends server/discover first. A proper discover result means the server is modern. So does a modern error such as UnsupportedProtocolVersion, because only a modern server knows that code. Any other error, or no answer at all, means the server is legacy, so the client falls back to initialize. Over HTTP it tries a modern request and reads the body of a 400 the same way.

The answer is a property of the server, not of the moment, so clients cache it instead of probing every time. A client asks again only when its cached discover result's ttlMs runs out, or when a call that used to work starts returning a version error, which means the server was upgraded underneath it.

A modern-only client can't use a legacy server, and a legacy-only client can't use a modern-only server. That's why many SDKs and hosts stay dual-era during the transition, and why the spec now promises at least twelve months' notice before removing a deprecated feature.

In plain words: a dual-era client asks "discover?" once. A real answer or a modern error means modern; anything else means legacy.

MODERN_ERRORS = {-32022, -32021}      # only a modern server knows these codes

def era(reply):
    """Decide from a server's reply to server/discover."""
    if reply is None:
        return "legacy"                    # no answer at all
    if "result" in reply:
        return "modern"
    code = reply["error"]["code"]
    return "modern" if code in MODERN_ERRORS else "legacy"

print(era({"result": {"supportedVersions": ["2026-07-28"]}}))
print(era({"error": {"code": -32022, "message": "Unsupported protocol version"}}))
print(era({"error": {"code": -32601, "message": "Method not found"}}))
print(era(None))

def era(reply):
    if "result" in reply:
        return "modern"
    return "modern" if reply["error"]["code"] in (-32022, -32021) else "legacy"

print(era({"error": {"code": -32601}}), era({"error": {"code": -32021}}))