Server Discovery

## Why discovery exists at all Before revision 2026-07-28, an MCP client learned what a server could do by opening a connection, sending `initialize`, reading the `InitializeResult`, and then sending `notifications/initialized`. That handshake was removed in 2026-07-28. MCP is now a stateless protocol: every request is self-contained and carries its own protocol version and capabilities in `params._meta`, and a server MUST NOT rely on prior requests over the same connection to establish context. That removal left one genuine gap. A client that has never spoken to a server still wants a cheap way to ask "which revisions do you speak, what do you offer, and is there anything I should tell the model about you?" `server/discover` is exactly that question, answered in one round-trip. ## The obligation is asymmetric Servers **MUST** implement `server/discover`. Clients **MAY** call it. That asymmetry is the single most commonly missed fact about the method. It follows directly from statelessness: because every request already declares `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities`, a client loses nothing structural by never discovering — it can send `tools/list` as its first message. But any client that *does* want to look before it leaps must be able to assume the method is there, on every conformant server, which is why the server side is a MUST. ## The request shape `DiscoverRequest` params carry **only** `_meta`. There are no arguments, no cursor, no filter — nothing to pass. The `_meta` object is the ordinary `RequestMetaObject`: the required `io.modelcontextprotocol/protocolVersion`, the required `io.modelcontextprotocol/clientCapabilities` (an empty object `{}` is legal), and the optional `io.modelcontextprotocol/clientInfo`. ## The result shape `DiscoverResult` contains: - **`resultType`** — `"complete"`. Every MCP result carries a required `resultType`; discovery is always a complete result, never the `"input_required"` interim form. - **`supportedVersions: string[]`** — the revision date-strings this server accepts. - **`capabilities`** — the server capability object, telling the client which feature areas the server offers. - **`instructions?`** — optional free-form text describing how to use this server. It moved here from the old `InitializeResult`. - **`ttlMs` and `cacheScope`** — required, inherited from `CacheableResult`. `ttlMs` says how long the client may cache this answer; `cacheScope` is `"public"` or `"private"` and says whether the cached copy may be shared across users or must be kept per-authorization. - **`_meta`** — SHOULD carry `io.modelcontextprotocol/serverInfo`, the server's self-reported name and version. `instructions` and `serverInfo` are the two fields that visibly migrated out of the removed handshake. ## What it is not It is not a handshake, and it does not negotiate anything. There is no agreement step in MCP 2026-07-28: the server simply accepts or rejects each request on its own merits, and `supportedVersions` is informational — the client reads it and decides what to send next. Calling `server/discover` also does not register the client or open anything. An open connection, such as a stdio subprocess, is not a conversation or a session, so a discover call earlier on the same pipe grants a later `tools/call` nothing. If a server needs the client to prove something, that must travel on the request that needs it. ## Trust `serverInfo` — like `clientInfo` — is self-reported and explicitly untrusted. Show it in a UI, log it, use it for telemetry; do not make an authorization or identity decision from it, and do not assume the `name` is globally unique across the servers a host has connected. ## In practice A typical host calls `server/discover` once when a server is first configured, renders the name, version and instructions to the user, caches the answer for `ttlMs` under the scope `cacheScope` names, and thereafter goes straight to the primitive calls it needs. A minimal script client may never call it at all — and that is a conformant client.