MCP's server/discover Call: What It Actually Tells Your Bot Before Connecting

What server/discover actually returns

MCP's 2026-07-28 specification made the protocol stateless: there's no more initialize handshake, and every request carries its own protocol version and capabilities in _meta. To give clients a way to learn about a server before committing to that per-request model, the spec added server/discover. The request carries no body beyond the standard _meta block identifying the client and its declared protocol version.

The response lists supported protocol versions and a capabilities object (tools, resources, and so on). It can also provide server identity in _meta and an optional instructions string. A complete response must carry the caching hints ttlMs and cacheScope. For a bot that talks to the same server repeatedly, those fields define a freshness window and whether a cached result may be shared across authorization contexts.

Crucially, calling it is optional. A client is free to send any request directly and handle a version error if one comes back, which means server/discover is a convenience, not a prerequisite for every connection.

Sources: Discovery - Model Context Protocol, Caching - Model Context Protocol.

When to call it, and when to skip it

The spec lists two concrete reasons to call server/discover. First, presenting server information: a client doesn't need to call it to use the server, but it's a convenient way to retrieve identity, capabilities, and supported versions in a single request instead of probing with separate tools/list, prompts/list, and resources/list calls. Second, on stdio, there's no HTTP status code to drive version fallback, so a client that supports both modern and legacy servers should send server/discover first and fall back on any error that isn't a recognized modern error.

If your bot only ever talks to one server whose version you already pinned at setup time, skipping the call is reasonable — just send the real tools/call request with the correct protocol version in _meta and catch UnsupportedProtocolVersionError if the server has moved on. The error response lists the versions the server does support, so your retry logic has what it needs without a separate round trip.

Where discover earns its cost is a bot that connects to servers it doesn't control — a plugin marketplace, a multi-tenant integration, or any setup where the server version might change between runs. One call up front tells you whether the server still speaks your protocol version and what primitives it exposes, before you've committed a real tool call to it.

Sources: Discovery - Model Context Protocol, Versioning and Compatibility - Model Context Protocol.

Worked example: a bot connecting to an unfamiliar calendar server

Illustrative case: a small-team bot needs to book meetings through a third-party calendar MCP server it hasn't talked to before. Before sending any tools/call, the bot's client sends server/discover with its own protocolVersion and clientCapabilities in _meta. The server answers with resultType: complete, supportedVersions listing 2026-07-28, a capabilities object showing it exposes tools and resources but not prompts, an instructions string describing what the server does, and a ttlMs of one hour with cacheScope set to private.

The bot's client caches that response for up to an hour in the same authorization context. It must not reuse a private-scoped result under a different access token, including a sibling worker's different account. If the bot instead receives UnsupportedProtocolVersionError from a real request, the error's supported list supplies the versions it can consider for a compatible retry, without requiring another discovery round trip.

If the server never implements discover at all — because it's still running the prior, handshake-based revision — the modern client's probe fails or the connection closes, and a dual-era client falls back to the older initialize exchange. The TypeScript SDK's migration guide documents exactly this probe policy: a child process that exits on the probe is treated as a legacy server, and the transport only spawns the real session once the era is known.

Sources: Discovery - Model Context Protocol, Supporting protocol revision 2026-07-28, Caching - Model Context Protocol.

Where this goes wrong

Three failure modes are worth planning for. First, stale caching: if your bot keeps a discovery result beyond its ttlMs and the server has since dropped a capability, the next tool call can fail. Use a conservative no-cache policy when the hint is absent or non-positive; the SDK guide documents zero and private scope as the defaults for missing or malformed hints. A TTL is a freshness hint rather than a promise that data cannot change. If a real tool call contradicts cached metadata, invalidate that snapshot and check again.

Second, version drift that discover won't catch on its own: discover tells you what a server supports right now, but it's a single snapshot. If your bot holds a persisted DiscoverResult across a long-lived process and the server is redeployed with a narrower capability set in between, the cached capabilities object is wrong until the TTL expires or the next real call fails.

Third, assuming every server implements discovery correctly. Servers implementing the 2026-07-28 revision must provide server/discover, while earlier handshake-based revisions have no such requirement. A dual-era stdio client probes and falls back after an unrecognized error or a bounded timeout, but it keeps negotiating modern versions after a recognized modern error. The SDK guide separately documents HTTP authentication, server-failure and timeout cases that reject the connection instead of establishing a legacy era. Preserve those transport-specific distinctions in diagnostics.

Sources: Discovery - Model Context Protocol, Supporting protocol revision 2026-07-28, Caching - Model Context Protocol.

The decision for your bot

Call server/discover when your bot connects to a server whose version or capabilities you can't guarantee ahead of time — marketplace servers, multi-tenant integrations, or anything you didn't pin at setup. Skip it when you've already fixed the server version in configuration and are willing to handle a version-mismatch error on the rare occasion it changes.

Either way, respect the caching hints if the server sends them, and build the legacy-fallback path if any server in your bot's connection list might still be running a pre-2026-07-28 revision. Don't build a bot that assumes every MCP server already speaks the current, discover-aware protocol — the fallback path in the spec exists because that assumption breaks in practice.

Sources: Discovery - Model Context Protocol, Versioning and Compatibility - Model Context Protocol.