One read of Model Context Protocolmcp-20261020T200724Z
306 pages moved out of 357 read.
Pages moved
306
significant first
Pages read
357
in this capture
Captured
20:07 UTC
Corpus hash
077a51951f96
corpus-hash
What this read moved
226-250 of 306, page 10 of 13This capture is too large to show at once. Changes 226-250 of 306 are below, significant first; the rest are on the following screens.
specification/2026-07-28/server/utilities/pagination Changed · +8 / -10 lines
from line 1
11# Pagination
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) supports paginating list operations that may return
64large result sets. Pagination allows servers to yield results in smaller chunks rather
75than all at once.
from line 8
108internet, but also useful for local integrations to avoid performance issues with large
119data sets.
1210
13<Note>
14 For brevity, the request examples on this page omit the `_meta` request
15 metadata (`io.modelcontextprotocol/protocolVersion`,
16 `io.modelcontextprotocol/clientInfo`, and
17 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
18 the required `_meta` fields; see
19 [`_meta`](/specification/2026-07-28/basic/index#meta).
20</Note>
11> [!NOTE]
12>
13> For brevity, the request examples on this page omit the `_meta` request
14> metadata (`io.modelcontextprotocol/protocolVersion`,
15> `io.modelcontextprotocol/clientInfo`, and
16> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
17> the required `_meta` fields; see
18> [`_meta`](/specification/2026-07-28/basic/index#meta).
2119
2220## Pagination Model
2321
specification/draft/basic/authorization/client-registration Changed · +6 / -8 lines
from line 1
11# Client Registration
22
3<div id="enable-section-numbers" />
4
53MCP supports three client registration mechanisms. Choose based on your scenario:
64
75* **[Client ID Metadata Documents](#client-id-metadata-documents)**: When client and server have no prior relationship (most common)
from line 133
135133
136134## Dynamic Client Registration
137135
138<Warning>
139 Dynamic Client Registration is deprecated. New implementations should use
140 [Client ID Metadata Documents](#client-id-metadata-documents) instead. This
141 option remains available for backwards compatibility with authorization
142 servers that do not support Client ID Metadata Documents.
143</Warning>
136> [!WARNING]
137>
138> Dynamic Client Registration is deprecated. New implementations should use
139> [Client ID Metadata Documents](#client-id-metadata-documents) instead. This
140> option remains available for backwards compatibility with authorization
141> servers that do not support Client ID Metadata Documents.
144142
145143MCP clients and authorization servers **MAY** support the
146144OAuth 2.0 Dynamic Client Registration Protocol [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)
specification/draft/basic/index Changed · +17 / -19 lines
from line 1
11# Overview
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol consists of several key components that work together:
64
75* **Base Protocol**: Core JSON-RPC message types
from line 197
199197 application-level handles) **MUST** be referenced by an explicit identifier
200198 the client passes on each request.
201199
202<Note>
203 This implies that an open connection, such as a STDIO process, is not a
204 conversation or session: clients may interleave unrelated requests on the same
205 transport, and a server must not treat connection or process identity as a
206 proxy for conversation or session continuity.
207</Note>
200> [!NOTE]
201>
202> This implies that an open connection, such as a STDIO process, is not a
203> conversation or session: clients may interleave unrelated requests on the same
204> transport, and a server must not treat connection or process identity as a
205> proxy for conversation or session continuity.
208206
209207Long-lived requests like
210208[`subscriptions/listen`](/specification/draft/basic/patterns/subscriptions)
from line 209
211209remain request/response; the response is just an open stream of notifications.
212210Their state is scoped to the request itself, not to the connection underneath.
213211
214<Info>
215 For a walkthrough of how the per-request model maps to SDK code, see the
216 [Architecture guide](/docs/draft/learn/architecture#example).
217</Info>
212> [!NOTE]
213>
214> For a walkthrough of how the per-request model maps to SDK code, see the
215> [Architecture guide](/docs/draft/learn/architecture#example).
218216
219217## Auth
220218
from line 397
399397| - | - | - | - |
400398| `io.modelcontextprotocol/serverInfo` | `Implementation` | No | Server name and version |
401399
402<Note>
403 `io.modelcontextprotocol/clientInfo` and `io.modelcontextprotocol/serverInfo`
404 are self-reported by the sender and are not verified by the protocol. They are
405 intended for display, logging, and debugging. Implementations **SHOULD NOT**
406 use them to change the behavior of the client or server, and **SHOULD NOT**
407 rely on them for security decisions.
408</Note>
400> [!NOTE]
401>
402> `io.modelcontextprotocol/clientInfo` and `io.modelcontextprotocol/serverInfo`
403> are self-reported by the sender and are not verified by the protocol. They are
404> intended for display, logging, and debugging. Implementations **SHOULD NOT**
405> use them to change the behavior of the client or server, and **SHOULD NOT**
406> rely on them for security decisions.
409407
410408On notifications delivered via a [`subscriptions/listen`][subscriptions-listen] stream,
411409the server **MUST** include `io.modelcontextprotocol/subscriptionId` in `_meta` so the
specification/draft/basic/patterns/mrtr Changed · +23 / -25 lines
from line 1
11# Multi Round-Trip Requests
22
3<div id="enable-section-numbers" />
3> [!NOTE]
4>
5> Multi Round-Trip Requests (MRTR) was introduced in this version of the MCP
6> specification. This replaces the previous approach of sending server-initiated
7> requests. Servers **MUST** send server-to-client requests (such as
8> `roots/list`, `sampling/createMessage`, or `elicitation/create`) using the
9> MRTR pattern. The previous pattern of server-initiated requests is no longer
10> supported. This is a breaking change.
411
5<Note>
6 Multi Round-Trip Requests (MRTR) was introduced in this version of the MCP
7 specification. This replaces the previous approach of sending server-initiated
8 requests. Servers **MUST** send server-to-client requests (such as
9 `roots/list`, `sampling/createMessage`, or `elicitation/create`) using the
10 MRTR pattern. The previous pattern of server-initiated requests is no longer
11 supported. This is a breaking change.
12</Note>
12> [!NOTE]
13>
14> For brevity, the request examples on this page omit the `_meta` request
15> metadata (`io.modelcontextprotocol/protocolVersion`,
16> `io.modelcontextprotocol/clientInfo`, and
17> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
18> the required `_meta` fields; see
19> [`_meta`](/specification/draft/basic/index#meta).
1320
14<Note>
15 For brevity, the request examples on this page omit the `_meta` request
16 metadata (`io.modelcontextprotocol/protocolVersion`,
17 `io.modelcontextprotocol/clientInfo`, and
18 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
19 the required `_meta` fields; see
20 [`_meta`](/specification/draft/basic/index#meta).
21</Note>
22
2321## Multi Round-Trip Requests
2422
2523The Model Context Protocol (MCP) defines several ways for servers to request additional information
from line 234
236234 * the authenticated principal, rejecting state presented by a different principal.
237235 * a short expiry (TTL), rejecting state presented after it lapses;
238236 * an identifier for the originating request, e.g. the method name and a digest of its salient parameters, rejecting state presented on a request that does not match.
239 <Warning>
240 Note that these measures bound the replay window and prevent cross-user
241 and cross-request reuse, but do not by themselves guarantee single-use.
242 Servers for which a given `requestState` must be consumed at most once
243 (e.g., one-time redemptions) **MUST** enforce that invariant server-side.
244 </Warning>
237 > [!WARNING]
238 >
239 > Note that these measures bound the replay window and prevent cross-user
240 > and cross-request reuse, but do not by themselves guarantee single-use.
241 > Servers for which a given `requestState` must be consumed at most once
242 > (e.g., one-time redemptions) **MUST** enforce that invariant server-side.
245243
2462446. Servers **MUST** include at least one of `inputRequests` or `requestState` in every `InputRequiredResult` response.
247245
specification/draft/basic/transports/streamable-http Changed · +66 / -68 lines
from line 1
11# Streamable HTTP
22
3<div id="enable-section-numbers" />
3> [!NOTE]
4>
5> Streamable HTTP was introduced in protocol version 2025-03-26 as a replacement
6> for the \[HTTP+SSE transport]\[http-sse] from protocol version 2024-11-05.
47
5<Info>
6 Streamable HTTP was introduced in protocol version 2025-03-26 as a replacement
7 for the [HTTP+SSE transport][http-sse] from protocol version 2024-11-05.
8</Info>
8> [!NOTE]
9>
10> Revision 2026-07-28 changed the behavior of Streamable HTTP. Clients must
11> ensure they handle backwards compatibility correctly. Changes included:
12>
13> * Removal of the GET stream endpoint.
14> * Removal of protocol-level sessions.
15>
16> See the [changelog](/specification/draft/changelog) and
17> [Backward Compatibility](#backward-compatibility) below.
918
10<Info>
11 Revision 2026-07-28 changed the behavior of Streamable HTTP. Clients must
12 ensure they handle backwards compatibility correctly. Changes included:
13
14 * Removal of the GET stream endpoint.
15 * Removal of protocol-level sessions.
16
17 See the [changelog](/specification/draft/changelog) and
18 [Backward Compatibility](#backward-compatibility) below.
19</Info>
20
2119In the **Streamable HTTP** transport, the server operates as an independent
2220process that can handle multiple client connections. At a glance:
2321
from line 83
8583 `Content-Type: text/event-stream` (an SSE response stream). The client
8684 **MUST** support both.
8785
88<Note>
89 This revision of the core protocol defines no client-to-server
90 *notifications* over Streamable HTTP. The only client-sent notification in
91 the core protocol, `notifications/cancelled`, is used only on the
92 [stdio](/specification/draft/basic/transports/stdio) transport; on
93 Streamable HTTP, closing the SSE response stream is itself the cancellation
94 signal and no `notifications/cancelled` message is expected (see
95 [Cancellation][cancellation]). The notification rules above describe the
96 transport mechanics for a notification POST; header requirements for
97 notification POSTs are not defined by this revision.
98</Note>
86> [!NOTE]
87>
88> This revision of the core protocol defines no client-to-server
89> *notifications* over Streamable HTTP. The only client-sent notification in
90> the core protocol, `notifications/cancelled`, is used only on the
91> [stdio](/specification/draft/basic/transports/stdio) transport; on
92> Streamable HTTP, closing the SSE response stream is itself the cancellation
93> signal and no `notifications/cancelled` message is expected (see
94> \[Cancellation]\[cancellation]). The notification rules above describe the
95> transport mechanics for a notification POST; header requirements for
96> notification POSTs are not defined by this revision.
9997
10098## Receiving Messages
10199
from line 132
134132them to the client, introducing unwanted latency and potentially breaking the
135133real-time nature of SSE communication.
136134
137<Note>
138 For long-lived streams — in particular the
139 [`subscriptions/listen`][subscriptions-listen] response stream — servers are
140 encouraged to periodically emit an SSE comment line (a line beginning with a
141 colon, e.g. `:\r\n`) as a keep-alive. This keeps the connection from being
142 closed by intermediaries or client idle timeouts during quiet periods when no
143 notifications are flowing. Per the [SSE specification][sse], any line beginning
144 with a colon is a comment that carries no event data; clients must ignore such
145 lines and must not treat them as malformed input.
146</Note>
135> [!NOTE]
136>
137> For long-lived streams — in particular the
138> \[`subscriptions/listen`]\[subscriptions-listen] response stream — servers are
139> encouraged to periodically emit an SSE comment line (a line beginning with a
140> colon, e.g. `:\r\n`) as a keep-alive. This keeps the connection from being
141> closed by intermediaries or client idle timeouts during quiet periods when no
142> notifications are flowing. Per the \[SSE specification]\[sse], any line beginning
143> with a colon is a comment that carries no event data; clients must ignore such
144> lines and must not treat them as malformed input.
147145
148146Resumable SSE streams via `Last-Event-ID` are not supported.
149147
from line 582
584582(e.g., a load balancer routing on the header value while the MCP server
585583executes based on the body value).
586584
587<Note>
588 When validating integer parameter values, servers **SHOULD** compare the
589 header value and the body value numerically rather than as strings (e.g.,
590 `42.0` and `42` are considered equal).
591</Note>
585> [!NOTE]
586>
587> When validating integer parameter values, servers **SHOULD** compare the
588> header value and the body value numerically rather than as strings (e.g.,
589> `42.0` and `42` are considered equal).
592590
593591When rejecting a request due to header validation failure, servers **MUST**
594592return HTTP status `400 Bad Request` and **MUST** include a JSON-RPC error
from line 623
625623 [Value Encoding](#value-encoding)) before comparing them to the body value.
626624* A header value contains invalid characters.
627625
628<Note>
629 Intermediaries **MUST** return an appropriate HTTP error status (e.g.,
630 `400 Bad Request`) for validation failures but are not required to return
631 a JSON-RPC error response.
632</Note>
626> [!NOTE]
627>
628> Intermediaries **MUST** return an appropriate HTTP error status (e.g.,
629> `400 Bad Request`) for validation failures but are not required to return
630> a JSON-RPC error response.
633631
634<Note>
635 Intermediaries that enforce policy based on mirrored headers (e.g., routing
636 or rate-limiting by tenant) **SHOULD** verify that the `MCP-Protocol-Version`
637 header indicates a version that requires header–body validation. If the
638 version is older or the header is absent, the intermediary **SHOULD** reject
639 the request rather than trusting unvalidated header values.
640</Note>
632> [!NOTE]
633>
634> Intermediaries that enforce policy based on mirrored headers (e.g., routing
635> or rate-limiting by tenant) **SHOULD** verify that the `MCP-Protocol-Version`
636> header indicates a version that requires header–body validation. If the
637> version is older or the header is absent, the intermediary **SHOULD** reject
638> the request rather than trusting unvalidated header values.
641639
642640## Backward Compatibility
643641
from line 684
686684
687685### HTTP+SSE Transport (2024-11-05)
688686
689<Warning>
690 **Deprecated**: The [HTTP+SSE transport][http-sse] from protocol version
691 2024-11-05 has been deprecated since protocol version `2025-03-26` and is
692 classified as Deprecated under the [feature lifecycle
693 policy](/community/feature-lifecycle#deprecating-a-feature)
694 ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
695 New implementations **SHOULD NOT** adopt it; existing implementations
696 **SHOULD** migrate to [Streamable
697 HTTP](/specification/draft/basic/transports/streamable-http). It is eligible
698 for removal in a future revision; see the [deprecated features
699 registry](/specification/draft/deprecated).
700</Warning>
687> [!WARNING]
688>
689> **Deprecated**: The \[HTTP+SSE transport]\[http-sse] from protocol version
690> 2024-11-05 has been deprecated since protocol version `2025-03-26` and is
691> classified as Deprecated under the [feature lifecycle
692> policy](/community/feature-lifecycle#deprecating-a-feature)
693> ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
694> New implementations **SHOULD NOT** adopt it; existing implementations
695> **SHOULD** migrate to [Streamable
696> HTTP](/specification/draft/basic/transports/streamable-http). It is eligible
697> for removal in a future revision; see the [deprecated features
698> registry](/specification/draft/deprecated).
701699
702700Clients and servers can maintain backward compatibility with the
703701deprecated [HTTP+SSE transport][http-sse] (from
specification/draft/client/elicitation Changed · +43 / -45 lines
from line 1
11# Elicitation
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to request additional
64information from users through the client during interactions. This flow allows clients to
75maintain control over user interactions and data sharing while enabling servers to gather
from line 19
2119their needs—the protocol itself does not mandate any specific user interaction
2220model.
2321
24<Warning>
25 For trust & safety and security:
22> [!WARNING]
23>
24> For trust & safety and security:
25>
26> * Servers **MUST NOT** use form mode elicitation to request sensitive information such as
27> passwords, API keys, access tokens, or payment credentials
28> * Servers **MUST** use [URL mode](#url-mode-elicitation-requests) for interactions involving
29> such sensitive information
30>
31> "Sensitive information" in this context refers to secrets and credentials that grant access or
32> authorize transactions. General contact or profile information (such as a name, email address,
33> or username) is not categorically prohibited; whether to request such data via form mode is at
34> the discretion of the server and subject to the user's ability to review and decline.
35>
36> MCP clients **MUST**:
37>
38> * Provide UI that makes it clear which server is requesting information
39> * Respect user privacy and provide clear decline and cancel options
40> * For form mode, allow users to review and modify their responses before sending
41> * For URL mode, clearly display the target domain/host and gather user consent before navigation to the target URL
2642
27 * Servers **MUST NOT** use form mode elicitation to request sensitive information such as
28 passwords, API keys, access tokens, or payment credentials
29 * Servers **MUST** use [URL mode](#url-mode-elicitation-requests) for interactions involving
30 such sensitive information
31
32 "Sensitive information" in this context refers to secrets and credentials that grant access or
33 authorize transactions. General contact or profile information (such as a name, email address,
34 or username) is not categorically prohibited; whether to request such data via form mode is at
35 the discretion of the server and subject to the user's ability to review and decline.
36
37 MCP clients **MUST**:
38
39 * Provide UI that makes it clear which server is requesting information
40 * Respect user privacy and provide clear decline and cancel options
41 * For form mode, allow users to review and modify their responses before sending
42 * For URL mode, clearly display the target domain/host and gather user consent before navigation to the target URL
43</Warning>
44
4543## Capabilities
4644
4745Clients that support elicitation **MUST** declare the `elicitation` capability in
from line 315
317315
318316### URL Mode Elicitation Requests
319317
320<Note>
321 **New feature:** URL mode elicitation is introduced in the `2025-11-25` version of the MCP specification. Its design and implementation may change in future protocol revisions.
322</Note>
318> [!NOTE]
319>
320> **New feature:** URL mode elicitation is introduced in the `2025-11-25` version of the MCP specification. Its design and implementation may change in future protocol revisions.
323321
324322URL mode elicitation enables servers to direct users to external URLs for out-of-band interactions that must not pass through the MCP client. This is essential for auth flows, payment processing, and other sensitive or secure operations.
325323
from line 329
331329
332330The `url` parameter **MUST** contain a valid URL.
333331
334<Note>
335 **Important**: URL mode elicitation is *not* for authorizing the MCP client's
336 access to the MCP server (that's handled by [MCP
337 authorization](../basic/authorization)). Instead, it's used when the MCP
338 server needs to obtain sensitive information or third-party authorization on
339 behalf of the user. The MCP client's bearer token remains unchanged. The
340 client's only responsibility is to provide the user with context about the
341 elicitation URL the server wants them to open.
342</Note>
332> [!NOTE]
333>
334> **Important**: URL mode elicitation is *not* for authorizing the MCP client's
335> access to the MCP server (that's handled by [MCP
336> authorization](../basic/authorization)). Instead, it's used when the MCP
337> server needs to obtain sensitive information or third-party authorization on
338> behalf of the user. The MCP client's bearer token remains unchanged. The
339> client's only responsibility is to provide the user with context about the
340> elicitation URL the server wants them to open.
343341
344342#### Example: Request Sensitive Data
345343
from line 469
471469* State storage **MUST** be protected against unauthorized access
472470* For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](../basic/authorization) when possible (e.g. `sub` claim)
473471
474<Note>
475 The examples in this section are non-normative and illustrate potential uses
476 of elicitation. Implementers should adapt these patterns to their specific
477 requirements while maintaining security best practices.
478</Note>
472> [!NOTE]
473>
474> The examples in this section are non-normative and illustrate potential uses
475> of elicitation. Implementers should adapt these patterns to their specific
476> requirements while maintaining security best practices.
479477
480478### URL Mode Elicitation for Sensitive Data
481479
from line 519
521519
522520Credentials obtained via URL mode elicitation are distinct from the MCP server credentials used by the MCP client. The MCP server **MUST NOT** transmit credentials obtained through URL mode elicitation to the MCP client.
523521
524<Note>
525 For additional background, refer to the [token passthrough
526 section](/docs/draft/tutorials/security/security_best_practices#token-passthrough)
527 of the Security Best Practices document to understand why MCP servers cannot
528 act as pass-through proxies.
529</Note>
522> [!NOTE]
523>
524> For additional background, refer to the [token passthrough
525> section](/docs/draft/tutorials/security/security_best_practices#token-passthrough)
526> of the Security Best Practices document to understand why MCP servers cannot
527> act as pass-through proxies.
530528
531529#### Implementation Pattern
532530
specification/draft/client/roots Changed · +11 / -13 lines
from line 1
11# Roots
22
3<div id="enable-section-numbers" />
4
5<Warning>
6 **Deprecated**: The Roots feature is deprecated as of protocol version
7 `2026-07-28`
8 ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
9 Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
10 in the specification for at least twelve months after this revision's release
11 before it becomes eligible for removal. New implementations **SHOULD NOT**
12 adopt it; existing implementations **SHOULD** migrate to passing directories
13 or files via tool parameters, resource URIs, or server configuration. See the
14 [deprecated features registry](/specification/draft/deprecated).
15</Warning>
3> [!WARNING]
4>
5> **Deprecated**: The Roots feature is deprecated as of protocol version
6> `2026-07-28`
7> ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
8> Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
9> in the specification for at least twelve months after this revision's release
10> before it becomes eligible for removal. New implementations **SHOULD NOT**
11> adopt it; existing implementations **SHOULD** migrate to passing directories
12> or files via tool parameters, resource URIs, or server configuration. See the
13> [deprecated features registry](/specification/draft/deprecated).
1614
1715The Model Context Protocol (MCP) provides a standardized way for clients to expose
1816filesystem "roots" to servers. Roots inform servers about the directories and files the
specification/draft/client/sampling Changed · +32 / -34 lines
from line 1
11# Sampling
22
3<div id="enable-section-numbers" />
3> [!WARNING]
4>
5> **Deprecated**: The Sampling feature is deprecated as of protocol version
6> `2026-07-28`
7> ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
8> Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
9> in the specification for at least twelve months after this revision's release
10> before it becomes eligible for removal. New implementations **SHOULD NOT**
11> adopt it; existing implementations **SHOULD** migrate to integrating directly
12> with LLM provider APIs. See the [deprecated features
13> registry](/specification/draft/deprecated).
414
5<Warning>
6 **Deprecated**: The Sampling feature is deprecated as of protocol version
7 `2026-07-28`
8 ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
9 Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
10 in the specification for at least twelve months after this revision's release
11 before it becomes eligible for removal. New implementations **SHOULD NOT**
12 adopt it; existing implementations **SHOULD** migrate to integrating directly
13 with LLM provider APIs. See the [deprecated features
14 registry](/specification/draft/deprecated).
15</Warning>
16
1715The Model Context Protocol (MCP) provides a standardized way for servers to request LLM
1816sampling ("completions" or "generations") from language models via clients. This flow
1917allows clients to maintain control over model access, selection, and permissions while
from line 28
3028their needs—the protocol itself does not mandate any specific user interaction
3129model.
3230
33<Warning>
34 For trust & safety and security, there **SHOULD** always
35 be a human in the loop with the ability to deny sampling requests.
31> [!WARNING]
32>
33> For trust & safety and security, there **SHOULD** always
34> be a human in the loop with the ability to deny sampling requests.
35>
36> Applications **SHOULD**:
37>
38> * Provide UI that makes it easy and intuitive to review sampling requests
39> * Allow users to view and edit prompts before sending
40> * Present generated responses for review before delivery
3641
37 Applications **SHOULD**:
38
39 * Provide UI that makes it easy and intuitive to review sampling requests
40 * Allow users to view and edit prompts before sending
41 * Present generated responses for review before delivery
42</Warning>
43
4442## Tools in Sampling
4543
4644Servers can request that the client's LLM use tools during sampling by providing a `tools` array and optional `toolChoice` configuration in their sampling requests. The tool definitions in the `tools` array are scoped to the sampling request — they don't need to correspond to registered tools. This enables servers to implement agentic behaviors where the LLM can call specially designated tools, receive results, and continue the conversation - all within a single sampling request flow.
from line 90
9290}
9391```
9492
95<Note>
96 The `includeContext` parameter values `"thisServer"` and `"allServers"` are
97 deprecated under the [feature lifecycle
98 policy](/community/feature-lifecycle#deprecating-a-feature)
99 ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596));
100 they will be removed no later than the Sampling feature itself. Servers
101 **SHOULD** avoid using these values (e.g. can just omit `includeContext` since
102 it defaults to `"none"`), and **SHOULD NOT** use them unless the client
103 declares `sampling.context` capability. See the [deprecated features
104 registry](/specification/draft/deprecated).
105</Note>
93> [!NOTE]
94>
95> The `includeContext` parameter values `"thisServer"` and `"allServers"` are
96> deprecated under the [feature lifecycle
97> policy](/community/feature-lifecycle#deprecating-a-feature)
98> ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596));
99> they will be removed no later than the Sampling feature itself. Servers
100> **SHOULD** avoid using these values (e.g. can just omit `includeContext` since
101> it defaults to `"none"`), and **SHOULD NOT** use them unless the client
102> declares `sampling.context` capability. See the [deprecated features
103> registry](/specification/draft/deprecated).
106104
107105## Protocol Messages
108106
specification/draft/index Changed · +5 / -9 lines
from line 1
11# Specification
22
3<div id="enable-section-numbers" />
4
53[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that
64enables seamless integration between LLM applications and external data sources and
75tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating
from line 123
125123
126124Explore the detailed specification for each protocol component:
127125
128<CardGroup cols={5}>
129 <Card title="Architecture" icon="sitemap" href="/specification/draft/architecture" />
126> **[Architecture](/specification/draft/architecture)**
130127
131 <Card title="Base Protocol" icon="code" href="/specification/draft/basic" />
128> **[Base Protocol](/specification/draft/basic)**
132129
133 <Card title="Server Features" icon="server" href="/specification/draft/server" />
130> **[Server Features](/specification/draft/server)**
134131
135 <Card title="Client Features" icon="user" href="/specification/draft/client" />
132> **[Client Features](/specification/draft/client)**
136133
137 <Card title="Contributing" icon="pencil" href="/community/contributing" />
138</CardGroup>
134> **[Contributing](/community/contributing)**
139135
specification/draft/server/discover Changed · +6 / -8 lines
from line 1
11# Discovery
22
3<div id="enable-section-numbers" />
4
53`server/discover` lets a client query a server's supported protocol versions,
64capabilities, and identity before sending any other requests. Servers **MUST**
75implement it.
from line 96
9896* `instructions`: Optional natural-language guidance for LLMs on how to use
9997 this server effectively
10098
101<Note>
102 `serverInfo` is self-reported by the server and is not verified by the
103 protocol. It is intended for display, logging, and debugging. Clients **SHOULD
104 NOT** use it to change their behavior, and **SHOULD NOT** rely on it for
105 security decisions.
106</Note>
99> [!NOTE]
100>
101> `serverInfo` is self-reported by the server and is not verified by the
102> protocol. It is intended for display, logging, and debugging. Clients **SHOULD
103> NOT** use it to change their behavior, and **SHOULD NOT** rely on it for
104> security decisions.
107105
specification/draft/server/index Changed · +3 / -5 lines
from line 20
2020
2121Explore these key primitives in more detail below:
2222
23<CardGroup cols={3}>
24 <Card title="Prompts" icon="message" href="/specification/draft/server/prompts" />
23> **[Prompts](/specification/draft/server/prompts)**
2524
26 <Card title="Resources" icon="file-lines" href="/specification/draft/server/resources" />
25> **[Resources](/specification/draft/server/resources)**
2726
28 <Card title="Tools" icon="wrench" href="/specification/draft/server/tools" />
29</CardGroup>
27> **[Tools](/specification/draft/server/tools)**
3028
specification/draft/server/prompts Changed · +14 / -16 lines
from line 1
11# Prompts
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt
64templates to clients. Prompts allow servers to provide structured messages and
75instructions for interacting with language models. Clients can discover available
86prompts, retrieve their contents, and provide arguments to customize them.
97
10<Note>
11 For brevity, the request examples on this page omit the `_meta` request
12 metadata (`io.modelcontextprotocol/protocolVersion`,
13 `io.modelcontextprotocol/clientInfo`, and
14 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
15 the required `_meta` fields; see
16 [`_meta`](/specification/draft/basic/index#meta).
17</Note>
8> [!NOTE]
9>
10> For brevity, the request examples on this page omit the `_meta` request
11> metadata (`io.modelcontextprotocol/protocolVersion`,
12> `io.modelcontextprotocol/clientInfo`, and
13> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
14> the required `_meta` fields; see
15> [`_meta`](/specification/draft/basic/index#meta).
1816
1917## User Interaction Model
2018
from line 26
2826
2927For example, as slash commands:
3028
31<img src="https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/specification/draft/server/slash-command.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=02e1902c84120c10cfa83d0234a0040d" alt="Example of prompt exposed as slash command" width="293" height="106" data-path="specification/draft/server/slash-command.png" />
29
3230
3331However, implementors are free to expose prompts through any interface pattern that suits
3432their needs—the protocol itself does not mandate any specific user interaction
from line 218
220218* `role`: Either "user" or "assistant" to indicate the speaker
221219* `content`: One of the following content types:
222220
223<Note>
224 All content types in prompt messages support optional
225 [annotations](/specification/draft/server/resources#annotations) for metadata
226 about audience, priority, and modification times.
227</Note>
221> [!NOTE]
222>
223> All content types in prompt messages support optional
224> [annotations](/specification/draft/server/resources#annotations) for metadata
225> about audience, priority, and modification times.
228226
229227#### Text Content
230228
specification/draft/server/resources Changed · +9 / -11 lines
from line 1
11# Resources
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to expose
64resources to clients. Resources allow servers to share data that provides context to
75language models, such as files, database schemas, or application-specific information.
from line 6
86Each resource is uniquely identified by a
97[URI](https://datatracker.ietf.org/doc/html/rfc3986).
108
11<Note>
12 For brevity, the request examples on this page omit the `_meta` request
13 metadata (`io.modelcontextprotocol/protocolVersion`,
14 `io.modelcontextprotocol/clientInfo`, and
15 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
16 the required `_meta` fields; see
17 [`_meta`](/specification/draft/basic/index#meta).
18</Note>
9> [!NOTE]
10>
11> For brevity, the request examples on this page omit the `_meta` request
12> metadata (`io.modelcontextprotocol/protocolVersion`,
13> `io.modelcontextprotocol/clientInfo`, and
14> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
15> the required `_meta` fields; see
16> [`_meta`](/specification/draft/basic/index#meta).
1917
2018## User Interaction Model
2119
from line 26
2826* Allow the user to search through and filter available resources
2927* Implement automatic context inclusion, based on heuristics or the AI model's selection
3028
31<img src="https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/specification/draft/server/resource-picker.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=2026c8851a10ac020117731076a486b9" alt="Example of resource context picker" width="174" height="181" data-path="specification/draft/server/resource-picker.png" />
29
3230
3331However, implementations are free to expose resources through any interface pattern that
3432suits their needs—the protocol itself does not mandate any specific user
specification/draft/server/tools Changed · +56 / -58 lines
from line 1
11# Tools
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by
64language models. Tools enable models to interact with external systems, such as querying
75databases, calling APIs, or performing computations. Each tool is uniquely identified by
86a name and includes metadata describing its schema.
97
10<Note>
11 For brevity, the request examples on this page omit the `_meta` request
12 metadata (`io.modelcontextprotocol/protocolVersion`,
13 `io.modelcontextprotocol/clientInfo`, and
14 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
15 the required `_meta` fields; see
16 [`_meta`](/specification/draft/basic/index#meta).
17</Note>
8> [!NOTE]
9>
10> For brevity, the request examples on this page omit the `_meta` request
11> metadata (`io.modelcontextprotocol/protocolVersion`,
12> `io.modelcontextprotocol/clientInfo`, and
13> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
14> the required `_meta` fields; see
15> [`_meta`](/specification/draft/basic/index#meta).
1816
1917## User Interaction Model
2018
from line 24
2624suits their needs—the protocol itself does not mandate any specific user
2725interaction model.
2826
29<Warning>
30 For trust & safety and security, there **SHOULD** always
31 be a human in the loop with the ability to deny tool invocations.
27> [!WARNING]
28>
29> For trust & safety and security, there **SHOULD** always
30> be a human in the loop with the ability to deny tool invocations.
31>
32> Applications **SHOULD**:
33>
34> * Provide UI that makes clear which tools are being exposed to the AI model
35> * Insert clear visual indicators when tools are invoked
36> * Present confirmation prompts to the user for operations, to ensure a human is in the
37> loop
3238
33 Applications **SHOULD**:
34
35 * Provide UI that makes clear which tools are being exposed to the AI model
36 * Insert clear visual indicators when tools are invoked
37 * Present confirmation prompts to the user for operations, to ensure a human is in the
38 loop
39</Warning>
40
4139## Capabilities
4240
4341Servers that support tools **MUST** declare the `tools` capability:
from line 295
297295 * Defaults to 2020-12 if no `$schema` field is present
298296* `annotations`: Optional properties describing tool behavior
299297
300<Warning>
301 For trust & safety and security, clients **MUST** consider tool annotations to
302 be untrusted unless they come from trusted servers.
303</Warning>
298> [!WARNING]
299>
300> For trust & safety and security, clients **MUST** consider tool annotations to
301> be untrusted unless they come from trusted servers.
304302
305303#### Tool Names
306304
from line 313
315313 * `DATA_EXPORT_v2`
316314 * `admin.tools.list`
317315
318<Note>
319 Tool name uniqueness is scoped to a single server. Clients or proxies that
320 aggregate tools from multiple servers **MAY** encounter naming collisions (for
321 example, two servers each exposing a `search` tool) and **SHOULD** implement a
322 disambiguation strategy such as prefixing tool names with a server identifier.
316> [!NOTE]
317>
318> Tool name uniqueness is scoped to a single server. Clients or proxies that
319> aggregate tools from multiple servers **MAY** encounter naming collisions (for
320> example, two servers each exposing a `search` tool) and **SHOULD** implement a
321> disambiguation strategy such as prefixing tool names with a server identifier.
322>
323> The server `name` (from `serverInfo`) is not guaranteed to be unique across
324> servers and **SHOULD NOT** be relied upon for disambiguation.
323325
324 The server `name` (from `serverInfo`) is not guaranteed to be unique across
325 servers and **SHOULD NOT** be relied upon for disambiguation.
326</Note>
327
328326#### x-mcp-header
329327
330328The `x-mcp-header` extension property allows servers to designate specific tool
from line 386
388386In this example, when the tool is called with `"region": "us-west1"`, the client adds
389387the header `Mcp-Param-Region: us-west1` to the HTTP request.
390388
391<Warning>
392 Server developers **SHOULD NOT** mark sensitive parameters (passwords, API keys, tokens,
393 PII) with `x-mcp-header`, as header values are visible to network intermediaries.
394</Warning>
389> [!WARNING]
390>
391> Server developers **SHOULD NOT** mark sensitive parameters (passwords, API keys, tokens,
392> PII) with `x-mcp-header`, as header values are visible to network intermediaries.
395393
396394### Tool Result
397395
from line 397
399397
400398**Unstructured** content is returned in the `content` field of a result, and can contain multiple content items of different types:
401399
402<Note>
403 All content types (text, image, audio, resource links, and embedded resources)
404 support optional
405 [annotations](/specification/draft/server/resources#annotations) that provide
406 metadata about audience, priority, and modification times. This is the same
407 annotation format used by resources and prompts.
408</Note>
400> [!NOTE]
401>
402> All content types (text, image, audio, resource links, and embedded resources)
403> support optional
404> [annotations](/specification/draft/server/resources#annotations) that provide
405> metadata about audience, priority, and modification times. This is the same
406> annotation format used by resources and prompts.
409407
410408#### Text Content
411409
from line 455
457455
458456Resource links support the same [Resource annotations](/specification/draft/server/resources#annotations) as regular resources to help clients understand how to use them.
459457
460<Info>
461 Resource links returned by tools are not guaranteed to appear in the results
462 of a `resources/list` request.
463</Info>
458> [!NOTE]
459>
460> Resource links returned by tools are not guaranteed to appear in the results
461> of a `resources/list` request.
464462
465463#### Embedded Resources
466464
from line 489
491489
492490For backwards compatibility, a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block.
493491
494<Note>
495 `structuredContent` is server-produced result data and is unrelated to LLM
496 "structured outputs" (schema-constrained model generation).
497</Note>
492> [!NOTE]
493>
494> `structuredContent` is server-produced result data and is unrelated to LLM
495> "structured outputs" (schema-constrained model generation).
498496
499497#### Output Schema
500498
from line 670
672670
673671## Stateful Tools
674672
675<Note>
676 This section is non-normative guidance for tool design. The protocol has no
677 concept of a state handle; from the wire's perspective a handle is an ordinary
678 string in a tool result and an ordinary argument to subsequent tool calls.
679</Note>
673> [!NOTE]
674>
675> This section is non-normative guidance for tool design. The protocol has no
676> concept of a state handle; from the wire's perspective a handle is an ordinary
677> string in a tool result and an ordinary argument to subsequent tool calls.
680678
681679MCP has no protocol-level session, so a server cannot rely on implicit
682680per-connection state to relate one tool call to the next. Servers that need to
specification/draft/server/utilities/caching Changed · +8 / -10 lines
from line 1
11# Caching
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) supports caching for some results. This allows clients to cache responses and reduce unnecessary re-fetching.
64Caching is complementary to [change notifications](#interaction-with-notifications)—both
75mechanisms can coexist.
from line 36
3836
3937Cacheable Results in MCP use two fields to provide caching hints to clients:
4038
41* The <b>Time-to-live (TTL) Field</b>,`ttlMs`, is an integer value in milliseconds specifying how long the client MAY consider the result fresh.
42* The <b>Cache Scope Field</b>,`cacheScope`, indicates the intended scope of the cached response, either `"public"` or `"private"`.
39* The **Time-to-live (TTL) Field**,`ttlMs`, is an integer value in milliseconds specifying how long the client MAY consider the result fresh.
40* The **Cache Scope Field**,`cacheScope`, indicates the intended scope of the cached response, either `"public"` or `"private"`.
4341
4442### Time-to-Live (TTL) Field
4543
from line 55
5755
5856Servers **MUST** provide a `ttlMs` value that is `>= 0`.
5957
60<Note>
61 TTL is a **freshness hint**, not a guarantee. Servers MAY change the
62 underlying data before the TTL expires. The TTL tells the client how long it
63 can reasonably avoid re-fetching, not how long the data is guaranteed to
64 remain unchanged.
65</Note>
58> [!NOTE]
59>
60> TTL is a **freshness hint**, not a guarantee. Servers MAY change the
61> underlying data before the TTL expires. The TTL tells the client how long it
62> can reasonably avoid re-fetching, not how long the data is guaranteed to
63> remain unchanged.
6664
6765#### Freshness Calculation
6866
specification/draft/server/utilities/completion Changed · +8 / -10 lines
from line 1
11# Completion
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to offer
64autocompletion suggestions for the arguments of prompts and resource templates. When
75users are filling in argument values for a specific prompt (identified by name) or
86resource template (identified by URI), servers can provide contextual suggestions.
97
10<Note>
11 For brevity, the request examples on this page omit the `_meta` request
12 metadata (`io.modelcontextprotocol/protocolVersion`,
13 `io.modelcontextprotocol/clientInfo`, and
14 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
15 the required `_meta` fields; see
16 [`_meta`](/specification/draft/basic/index#meta).
17</Note>
8> [!NOTE]
9>
10> For brevity, the request examples on this page omit the `_meta` request
11> metadata (`io.modelcontextprotocol/protocolVersion`,
12> `io.modelcontextprotocol/clientInfo`, and
13> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
14> the required `_meta` fields; see
15> [`_meta`](/specification/draft/basic/index#meta).
1816
1917## User Interaction Model
2018
specification/draft/server/utilities/logging Changed · +12 / -14 lines
from line 1
11# Logging
22
3<div id="enable-section-numbers" />
4
5<Warning>
6 **Deprecated**: The Logging feature is deprecated as of protocol version
7 `2026-07-28`
8 ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
9 Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
10 in the specification for at least twelve months after this revision's release
11 before it becomes eligible for removal. New implementations **SHOULD NOT**
12 adopt it; existing implementations **SHOULD** migrate to logging to `stderr`
13 for stdio transports, or to [OpenTelemetry](https://opentelemetry.io/) for
14 structured observability. See the [deprecated features
15 registry](/specification/draft/deprecated).
16</Warning>
3> [!WARNING]
4>
5> **Deprecated**: The Logging feature is deprecated as of protocol version
6> `2026-07-28`
7> ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
8> Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
9> in the specification for at least twelve months after this revision's release
10> before it becomes eligible for removal. New implementations **SHOULD NOT**
11> adopt it; existing implementations **SHOULD** migrate to logging to `stderr`
12> for stdio transports, or to [OpenTelemetry](https://opentelemetry.io/) for
13> structured observability. See the [deprecated features
14> registry](/specification/draft/deprecated).
1715
1816The Model Context Protocol (MCP) provides a standardized way for servers to send
1917structured log messages to clients. Clients control logging verbosity per-request via
specification/draft/server/utilities/pagination Changed · +8 / -10 lines
from line 1
11# Pagination
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) supports paginating list operations that may return
64large result sets. Pagination allows servers to yield results in smaller chunks rather
75than all at once.
from line 8
108internet, but also useful for local integrations to avoid performance issues with large
119data sets.
1210
13<Note>
14 For brevity, the request examples on this page omit the `_meta` request
15 metadata (`io.modelcontextprotocol/protocolVersion`,
16 `io.modelcontextprotocol/clientInfo`, and
17 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
18 the required `_meta` fields; see
19 [`_meta`](/specification/draft/basic/index#meta).
20</Note>
11> [!NOTE]
12>
13> For brevity, the request examples on this page omit the `_meta` request
14> metadata (`io.modelcontextprotocol/protocolVersion`,
15> `io.modelcontextprotocol/clientInfo`, and
16> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
17> the required `_meta` fields; see
18> [`_meta`](/specification/draft/basic/index#meta).
2119
2220## Pagination Model
2321
community/interest-groups/auth Changed · +1 / -1 lines
from line 38
3838
3939* **[Security IG](/community/interest-groups/security)**: token-audience confusion, issuer validation, and account-linking risks sit at the boundary between the two groups
4040* **[Transports WG](/community/working-groups/transports)**: authorization is currently specified at the HTTP transport level; changes to transports affect where credentials are carried
41* **Agents WG**: delegated/on-behalf-of access and consent for multi-agent chains overlap heavily with agentic use cases
41* **Agents IG**: delegated/on-behalf-of access and consent for multi-agent chains overlap heavily with agentic use cases
4242* **[Server Card WG](/community/working-groups/server-card) / [Registry](/community/working-groups/registry)**: client and server identity, discovery metadata, and trust establishment intersect with how authorization servers and resource servers are located and verified
4343* **SDK Maintainers**: SDKs ship the auth client implementations; IG findings should inform cross-SDK auth ergonomics and defaults
4444
community/interest-groups/scientific-computing Changed · +1 / -1 lines
from line 44
4444
4545### Related Groups
4646
47* **[Agents WG](/community/working-groups/agents)**: Tasks are the foundation for the long-running
47* **[Tasks and Events WG](/community/working-groups/tasks-events)**: Tasks are the foundation for the long-running
4848 simulation and job-submission workflows for high-performance computing
4949* **[Interceptors WG](/community/working-groups/interceptors)**: interceptors are a potential
5050 implementation path for validating correctness and normalizing units between clients and servers
community/working-groups/filesystems Changed · +1 / -1 lines
from line 50
5050* **[Skills Over MCP WG](/community/working-groups/skills-over-mcp).** The published
5151 [Skills extension](/extensions/skills/overview) uses Resources for file reads and defines optional directory reading.
5252 It does not depend on filesystem write operations; coordinate on future resource operations that affect skills.
53* **Agents WG.** Multi-agent and job orchestration systems are the motivating consumers of a shared write path.
53* **Agents IG.** Multi-agent and job orchestration systems are the motivating consumers of a shared write path.
5454
5555## Leadership
5656
community/working-groups/skills-over-mcp Changed · +2 / -2 lines
from line 34
3434* **Reference Implementations**: SDK components and reference servers demonstrating
3535 skill discovery and consumption patterns
3636* **Cross-Cutting Concerns**: Coordination with Registry WG (skills discovery/distribution,
37 registry schema changes), Agents WG (skill activation, server metadata consumption),
37 registry schema changes), Agents IG (skill activation, server metadata consumption),
3838 [Progressive Disclosure WG](/community/working-groups/progressive-disclosure) (progressive disclosure patterns), and external projects including
3939 the [Agent Skills](https://agentskills.io/) spec (content format and well-known URI
4040 discovery), FastMCP, and PydanticAI
from line 53
5353
5454### Related Groups
5555
56* **Agents WG** — How agents consume server metadata, skill activation
56* **Agents IG** — How agents consume server metadata, skill activation
5757* **Registry WG** — Skills discovery/distribution, registry schema changes
5858* **[Progressive Disclosure WG](/community/working-groups/progressive-disclosure)** — Progressive disclosure patterns
5959
docs/2024-11-05/develop/clients/client-best-practices Changed · +2 / -2 lines
from line 10
1010
1111Naive MCP host implementations pass the tool definitions of every connected server directly to the model at the start of each conversation. For a handful of tools, this is perfectly reasonable. But when a host has access to dozens of servers exposing hundreds of tools, those definitions alone can consume the majority of the context window before the model has even read the user's message.
1212
13<img src="https://mintcdn.com/mcp/JXfd5cBmEUh_qPUI/images/progressive-discovery.svg?fit=max&auto=format&n=JXfd5cBmEUh_qPUI&q=85&s=db39f47006107f04af43b5eeae2d6022" alt="Comparison of loading all tools upfront versus discovering tools on demand. The upfront approach consumes ~150,000 tokens on definitions alone, while progressive discovery uses ~2,000 tokens by loading only what the task requires." width="760" height="440" data-path="images/progressive-discovery.svg" />
13
1414
1515Progressive discovery avoids this:
1616
from line 156
156156Programmatic tool calling is powerful and allows for more efficient use of MCP tools and resources, but requires
157157clients to implement a sandbox environment.
158158
159<img src="https://mintcdn.com/mcp/JXfd5cBmEUh_qPUI/images/programmatic-tool-calling.svg?fit=max&auto=format&n=JXfd5cBmEUh_qPUI&q=85&s=a2be82d097bb7cd7c7fd415918b1571d" alt="Comparison of direct tool calling versus programmatic tool calling. Direct calling passes every intermediate result through the model (~100K+ tokens). Programmatic calling sends a ~200-token script to a sandbox, which executes the tool calls and returns a ~15-token summary." width="900" height="900" data-path="images/programmatic-tool-calling.svg" />
159
160160
161161### How It Works
162162
docs/2025-03-26/develop/clients/client-best-practices Changed · +2 / -2 lines
from line 10
1010
1111Naive MCP host implementations pass the tool definitions of every connected server directly to the model at the start of each conversation. For a handful of tools, this is perfectly reasonable. But when a host has access to dozens of servers exposing hundreds of tools, those definitions alone can consume the majority of the context window before the model has even read the user's message.
1212
13<img src="https://mintcdn.com/mcp/JXfd5cBmEUh_qPUI/images/progressive-discovery.svg?fit=max&auto=format&n=JXfd5cBmEUh_qPUI&q=85&s=db39f47006107f04af43b5eeae2d6022" alt="Comparison of loading all tools upfront versus discovering tools on demand. The upfront approach consumes ~150,000 tokens on definitions alone, while progressive discovery uses ~2,000 tokens by loading only what the task requires." width="760" height="440" data-path="images/progressive-discovery.svg" />
13
1414
1515Progressive discovery avoids this:
1616
from line 156
156156Programmatic tool calling is powerful and allows for more efficient use of MCP tools and resources, but requires
157157clients to implement a sandbox environment.
158158
159<img src="https://mintcdn.com/mcp/JXfd5cBmEUh_qPUI/images/programmatic-tool-calling.svg?fit=max&auto=format&n=JXfd5cBmEUh_qPUI&q=85&s=a2be82d097bb7cd7c7fd415918b1571d" alt="Comparison of direct tool calling versus programmatic tool calling. Direct calling passes every intermediate result through the model (~100K+ tokens). Programmatic calling sends a ~200-token script to a sandbox, which executes the tool calls and returns a ~15-token summary." width="900" height="900" data-path="images/programmatic-tool-calling.svg" />
159
160160
161161### How It Works
162162
docs/2025-06-18/develop/clients/client-best-practices Changed · +2 / -2 lines
from line 10
1010
1111Naive MCP host implementations pass the tool definitions of every connected server directly to the model at the start of each conversation. For a handful of tools, this is perfectly reasonable. But when a host has access to dozens of servers exposing hundreds of tools, those definitions alone can consume the majority of the context window before the model has even read the user's message.
1212
13<img src="https://mintcdn.com/mcp/JXfd5cBmEUh_qPUI/images/progressive-discovery.svg?fit=max&auto=format&n=JXfd5cBmEUh_qPUI&q=85&s=db39f47006107f04af43b5eeae2d6022" alt="Comparison of loading all tools upfront versus discovering tools on demand. The upfront approach consumes ~150,000 tokens on definitions alone, while progressive discovery uses ~2,000 tokens by loading only what the task requires." width="760" height="440" data-path="images/progressive-discovery.svg" />
13
1414
1515Progressive discovery avoids this:
1616
from line 156
156156Programmatic tool calling is powerful and allows for more efficient use of MCP tools and resources, but requires
157157clients to implement a sandbox environment.
158158
159<img src="https://mintcdn.com/mcp/JXfd5cBmEUh_qPUI/images/programmatic-tool-calling.svg?fit=max&auto=format&n=JXfd5cBmEUh_qPUI&q=85&s=a2be82d097bb7cd7c7fd415918b1571d" alt="Comparison of direct tool calling versus programmatic tool calling. Direct calling passes every intermediate result through the model (~100K+ tokens). Programmatic calling sends a ~200-token script to a sandbox, which executes the tool calls and returns a ~15-token summary." width="900" height="900" data-path="images/programmatic-tool-calling.svg" />
159
160160
161161### How It Works
162162