The Model Context Protocol server discovery operation

See also

Sources

1. 1
   The project's announcement of the 2026-07-28 specification describes server/discover as a new RPC for learning a server's capabilities up front and says it is not required.

   The 2026-07-28 Specification · sentence beginning If a client wants to learn a server's capabilities before doing anything else · Checked 2026-09-30
2. 2
   A cached response is identified by the request method together with the request parameters that affect the result, and clients MUST NOT serve it for a request whose method or parameters differ.

   Model Context Protocol specification 2026-07-28, Caching · section Cache Key, first paragraph · Checked 2026-09-30
3. 3
   The Caching page requires servers to include caching hints on complete results of six operations: server/discover, tools/list, prompts/list, resources/list, resources/templates/list and resources/read.

   Model Context Protocol specification 2026-07-28, Caching · section Cacheable Results, bulleted list · Checked 2026-09-30
4. 4
   The Caching page's guidance on choosing a cache scope addresses lists of tools, prompts and resource templates, resources/read results and per-user filtered lists, and does not say which scope a server/discover result should use.

   Model Context Protocol specification 2026-07-28, Caching · section Choosing a Cache Scope · Checked 2026-09-30
5. 5
   cacheScope is either "public", meaning any client, shared gateway or caching proxy MAY store and serve the response to any user, or "private", meaning the cache MUST NOT be shared across authorization contexts.

   Model Context Protocol specification 2026-07-28, Caching · section Cache Scope Field, table · Checked 2026-09-30
6. 6
   Optional protocol extensions are advertised in the extensions field of capabilities, a map of extension identifiers to per-extension settings objects, where an empty object means support with no additional settings.

   Model Context Protocol specification 2026-07-28, Versioning and Compatibility · section Extension Negotiation · Checked 2026-09-30
7. 7
   The 2026-07-28 changelog entry for ttlMs and cacheScope names five operations (tools/list, prompts/list, resources/list, resources/read, resources/templates/list) and does not name server/discover, so the spec's own pages disagree on whether the enumerated set is five or six.disputed

   Model Context Protocol specification 2026-07-28, Key Changes · section Minor changes, item 5 · Checked 2026-09-30
8. 8
   Calling server/discover is optional for clients: a client may invoke any RPC directly and handle UnsupportedProtocolVersionError if the server does not support the requested version.

   Model Context Protocol specification 2026-07-28, Discovery · section When to Call, first paragraph · Checked 2026-09-30
9. 9
   The era determination is a property of the server, and clients SHOULD cache it for the lifetime of the server process (stdio) or origin (HTTP), MAY persist it across restarts, and re-probe if the cached assumption later fails.

   Model Context Protocol specification 2026-07-28, Versioning and Compatibility · section Backward Compatibility with Initialization-Based Versions, paragraph beginning The era determination · Checked 2026-09-30
10. 10
    The Versioning page defines modern as protocol versions that carry version, identity and capabilities as per-request metadata (2026-07-28 and later) and legacy as versions that establish a session with an initialize handshake (2025-11-25 and earlier).

    Model Context Protocol specification 2026-07-28, Versioning and Compatibility · section Terminology · Checked 2026-09-30
11. 11
    The example discovery response on the Discovery page carries ttlMs 3600000 and cacheScope "public".

    Model Context Protocol specification 2026-07-28, Discovery · section Response, example JSON · Checked 2026-09-30
12. 12
    Revision 2026-07-28 removes the initialize and notifications/initialized handshake; every request instead carries its protocol version and client capabilities in _meta.

    Model Context Protocol specification 2026-07-28, Key Changes · section Major changes, item 2 · Checked 2026-09-30
13. 13
    A server/discover POST over Streamable HTTP therefore needs the MCP-Protocol-Version header and Mcp-Method: server/discover, and no Mcp-Name header.inferred

    Model Context Protocol specification 2026-07-28, Streamable HTTP · section Request Metadata, Standard Request Headers table · Checked 2026-09-30
14. 14
    On Streamable HTTP a dual-era client MAY detect the server's era by attempting a modern request and, on 400 Bad Request, inspecting the body: a recognized modern JSON-RPC error means a modern server, anything else means fall back to initialize.

    Model Context Protocol specification 2026-07-28, Streamable HTTP · section Backward Compatibility, first paragraph and bullets · Checked 2026-09-30
15. 15
    On Streamable HTTP every POST MUST include MCP-Protocol-Version matching the body's protocolVersion, Mcp-Method is required for all requests, and Mcp-Name is required only for tools/call, resources/read and prompts/get.

    Model Context Protocol specification 2026-07-28, Streamable HTTP · section Request Metadata, Protocol Version Header and Standard Request Headers table · Checked 2026-09-30
16. 16
    On Streamable HTTP a server that does not implement the requested RPC method MUST respond with 404 Not Found and a JSON-RPC error with code -32601.

    Model Context Protocol specification 2026-07-28, Streamable HTTP · section Protocol Version Header, paragraph on unimplemented RPC method · Checked 2026-09-30
17. 17
    server/discover was added in protocol revision 2026-07-28 under SEP-2575, listed as major change 3 in the changelog against revision 2025-11-25.

    Model Context Protocol specification 2026-07-28, Key Changes · section Major changes, item 3 · Checked 2026-09-30
18. 18
    Per the compatibility matrix, a modern-only client against a legacy server fails, and on stdio clients SHOULD send server/discover first so the failure is deterministic and an actionable error can be shown to the user.

    Model Context Protocol specification 2026-07-28, Versioning and Compatibility · section Compatibility Matrix, row Modern client and Legacy server · Checked 2026-09-30
19. 19
    The JSON-RPC method string for the discovery operation is "server/discover".

    Model Context Protocol specification 2026-07-28, Discovery · section Request, example JSON, method field · Checked 2026-09-30
20. 20
    A client that supports only modern versions does not need to probe on stdio, but probing is still RECOMMENDED because some legacy servers would process an era-ambiguous method such as tools/call under legacy semantics, and the probe gives a deterministic failure instead.

    stdio · section Backward Compatibility, penultimate paragraph · Checked 2026-09-30
21. 21
    The notification types a client can opt in to on subscriptions/listen are toolsListChanged, promptsListChanged, resourcesListChanged and resourceSubscriptions; none signals a change to a server's DiscoverResult, so freshness of a cached discovery result appears to rest on ttlMs alone.inferred

    Model Context Protocol specification 2026-07-28, Key Changes · section Major changes, item 4 · Checked 2026-09-30
22. 22
    server/discover lets a client query a server's supported protocol versions, capabilities and identity before sending any other request.

    Model Context Protocol specification 2026-07-28, Discovery · Discovery page, opening paragraph · Checked 2026-09-30
23. 23
    The Architecture overview says that in the Python SDK discovery happens while the client connects and the results are then available on the client object.

    Architecture overview · section Example, step Discovery, How This Works in AI Applications · Checked 2026-09-30
24. 24
    The release-candidate announcement says the candidate was locked on May 21, 2026 and the final specification would be published on July 28, 2026.

    The 2026-07-28 MCP Specification Release Candidate · sentence beginning The release candidate is locked as of · Checked 2026-09-30
25. 25
    A server/discover request carries no body parameters beyond the standard per-request _meta.

    Model Context Protocol specification 2026-07-28, Discovery · section Request, first sentence · Checked 2026-09-30
26. 26
    Every client request, server/discover included, must carry io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in _meta; clientInfo is optional but SHOULD be sent; a request missing a required field MUST be rejected with -32602, and with 400 Bad Request on HTTP.

    Overview (base protocol) · section General fields, _meta, Per-request protocol fields table and following paragraphs · Checked 2026-09-30
27. 27
    DiscoverResult.capabilities reports the capabilities the server supports, such as tools, resources and prompts.

    Model Context Protocol specification 2026-07-28, Discovery · section Data Types, DiscoverResult, capabilities bullet · Checked 2026-09-30
28. 28
    In schema.ts for revision 2026-07-28, DiscoverResult extends CacheableResult, whose ttlMs and cacheScope members are declared without the optional marker.

    MCP TypeScript schema, protocol revision 2026-07-28 (schema.ts) · interface DiscoverResult; interface CacheableResult · Checked 2026-09-30
29. 29
    DiscoverResult.instructions is an optional field holding natural-language guidance for LLMs on how to use the server effectively.

    Model Context Protocol specification 2026-07-28, Discovery · section Data Types, DiscoverResult, instructions bullet · Checked 2026-09-30
30. 30
    In revision 2026-07-28 the server's name and version are carried in the discovery result's _meta under the key io.modelcontextprotocol/serverInfo, which servers SHOULD include; it is not a top-level DiscoverResult field.

    Model Context Protocol specification 2026-07-28, Discovery · section Data Types, DiscoverResult, serverInfo bullet; section Response, example JSON · Checked 2026-09-30
31. 31
    DiscoverResult.supportedVersions lists the protocol versions the server supports, and the client should choose one of them for subsequent requests.

    Model Context Protocol specification 2026-07-28, Discovery · section Data Types, DiscoverResult, supportedVersions bullet · Checked 2026-09-30
32. 32
    The Discovery page states that the server/discover operation supports caching, linking to the Caching utility.

    Model Context Protocol specification 2026-07-28, Discovery · section Response, first paragraph · Checked 2026-09-30
33. 33
    Because the base-protocol page names the TypeScript schema as the source of truth and that schema has DiscoverResult extend CacheableResult, the changelog's five-item list is more plausibly an incomplete enumeration than a statement that server/discover results carry no caching hints.inferred

    Overview (base protocol) · section Schema · Checked 2026-09-30
34. 34
    In schema.ts for revision 2026-07-28, DiscoverRequest declares method "server/discover" and a non-optional params member of type RequestParams.

    MCP TypeScript schema, protocol revision 2026-07-28 (schema.ts) · interface DiscoverRequest · Checked 2026-09-30
35. 35
    The SEP-2549 pull request, as summarised, scopes its caching fields to tools/list, prompts/list, resources/list, resources/read and resources/templates/list and does not mention server/discover.

    SEP-2549: TTL for List Results (pull request 2549) · pull request description · Checked 2026-09-30
36. 36
    SEP-2575's FAQ says server/discover overlaps with the MCP Server Card proposal (a .well-known/mcp.json document for HTTP discovery), that both are intentionally retained, and that server/discover gives a uniform RPC across HTTP and stdio.

    SEP-2575: Make MCP Stateless · section FAQ, How does server/discover relate to the MCP Server Card? · Checked 2026-09-30
37. 37
    The SEP-2575 page records that pull request 3002, after the SEP became Final, introduced io.modelcontextprotocol/serverInfo in result _meta and removed the top-level DiscoverResult.serverInfo field, and also made clientInfo optional.

    SEP-2575: Make MCP Stateless · section Changes since SEP became Final, first and second bullets · Checked 2026-09-30
38. 38
    SEP-2575 as accepted defined DiscoverResult with a top-level serverInfo field of type Implementation.

    SEP-2575: Make MCP Stateless · section Discovery for Server Capabilities, server/discover RPC, Response Schema · Checked 2026-09-30
39. 39
    SEP-2575 as accepted told a dual-era stdio client to fall back to initialize when server/discover returned Unsupported protocol version or Method not found; the published stdio page instead treats UnsupportedProtocolVersionError as proof of a modern server.

    SEP-2575: Make MCP Stateless · section Backward Compatibility, Client (supporting vPrev, vPost) to Server (vPrev), numbered step 3 · Checked 2026-09-30
40. 40
    SEP-2575 describes server/discover as the component that takes over capability discovery from the removed initialize handshake, with client capabilities handled per request.

    SEP-2575: Make MCP Stateless · section Deprecated and Removed RPCs, first bullet; section Rationale, Separation of Concerns · Checked 2026-09-30
41. 41
    In MCP protocol revision 2026-07-28, every server MUST implement the server/discover operation.

    Model Context Protocol specification 2026-07-28, Discovery · Discovery page, opening paragraph · Checked 2026-09-30
42. 42
    serverInfo is self-reported and not verified by the protocol; clients SHOULD NOT use it to change their behaviour and SHOULD NOT rely on it for security decisions.

    Model Context Protocol specification 2026-07-28, Discovery · section Data Types, DiscoverResult, Note block · Checked 2026-09-30
43. 43
    Clients MAY re-fetch before the TTL expires when they have reason to believe the data changed, and MAY serve a stale response if an error occurs while re-fetching.

    Model Context Protocol specification 2026-07-28, Caching · section Freshness Calculation, last two paragraphs · Checked 2026-09-30
44. 44
    The stdio fallback MUST NOT be keyed to one specific error code, because legacy servers answer unknown pre-initialize requests with implementation-defined errors (commonly -32601 or -32602) or not at all.

    stdio · section Backward Compatibility, paragraph after the outcome list · Checked 2026-09-30
45. 45
    If the stdio probe returns any other error, or the server does not respond within a reasonable timeout, the server is legacy and the client falls back to the initialize handshake.

    stdio · section Backward Compatibility, third outcome bullet · Checked 2026-09-30
46. 46
    If the stdio probe returns a recognized modern JSON-RPC error such as UnsupportedProtocolVersionError, the server is modern: the client uses a version from the error's supported list and does not fall back to initialize.

    stdio · section Backward Compatibility, second outcome bullet · Checked 2026-09-30
47. 47
    If the stdio probe returns a DiscoverResult, the server is modern and the client selects a mutually supported version from supportedVersions and continues.

    stdio · section Backward Compatibility, first outcome bullet · Checked 2026-09-30
48. 48
    On stdio, a client that supports both modern (per-request _meta) and legacy (initialize handshake) servers SHOULD send server/discover before any other request, with its preferred modern version in _meta.

    stdio · section Backward Compatibility, first paragraph · Checked 2026-09-30
49. 49
    TTL is a freshness hint and not a guarantee: a server may change the underlying data before the TTL expires.

    Model Context Protocol specification 2026-07-28, Caching · section Time-to-Live (TTL) Field, Note block · Checked 2026-09-30
50. 50
    Clients SHOULD NOT treat ttlMs as a polling interval that triggers background refetches; implementations that do poll MUST apply jitter and backoff.

    Model Context Protocol specification 2026-07-28, Caching · section Freshness Calculation · Checked 2026-09-30
51. 51
    ttlMs is an integer number of milliseconds for which the client MAY consider a cacheable result fresh, analogous to HTTP Cache-Control max-age, and servers MUST provide a value of zero or more.

    Model Context Protocol specification 2026-07-28, Caching · section Cacheable Model, Time-to-Live (TTL) Field · Checked 2026-09-30
52. 52
    A ttlMs of 0 means the response SHOULD be considered immediately stale; if ttlMs is absent clients SHOULD assume 0, and a negative value SHOULD be ignored and treated as 0.

    Model Context Protocol specification 2026-07-28, Caching · section Time-to-Live (TTL) Field, bulleted list · Checked 2026-09-30
53. 53
    A server that does not implement the requested protocol version MUST respond with UnsupportedProtocolVersionError, JSON-RPC code -32022, whose data lists the supported versions and echoes the requested one.

    Model Context Protocol specification 2026-07-28, Versioning and Compatibility · section Protocol Version Negotiation, second paragraph and example JSON · Checked 2026-09-30
54. 54
    The Discovery page names presenting server information as one use: a client can show what a server supports from a single server/discover response instead of probing with separate tools/list, prompts/list and resources/list requests.

    Model Context Protocol specification 2026-07-28, Discovery · section When to Call, bullet Presenting server information · Checked 2026-09-30

Documents

Cite this page

WarmTransfer. (2026, September 30). The Model Context Protocol server discovery operation. WarmTransfer. https://warmtransfer.net/knowledge/mcp-discovery-operation

@misc{warmtransfer-mcp-discovery-operation,
  title  = {The Model Context Protocol server discovery operation},
  author = {{WarmTransfer}},
  year   = {2026},
  url    = {https://warmtransfer.net/knowledge/mcp-discovery-operation},
  note   = {Verified 2026-09-30}
}