One read of Model Context Protocolmcp-20261022T203719Z
295 pages moved out of 357 read.
Pages moved
295
significant first
Pages read
357
in this capture
Captured
20:37 UTC
Corpus hash
3ef457b31340
full-sweep
What this read moved
51-75 of 295, page 3 of 12This capture is too large to show at once. Changes 51-75 of 295 are below, significant first; the rest are on the following screens.
docs/2025-06-18/learn/versioning Changed · +4 / -4 lines
from line 18
1818 receive backwards compatible changes.
1919* **Final**: past, complete specifications that will not be changed.
2020
21The **current** protocol version is [**2025-11-25**](/specification/2025-11-25/).
21The **current** protocol version is [**2025-11-25**](/specification/2025-11-25.md).
2222
2323## Feature States
2424
2525Individual features of the specification may additionally be marked as
2626**Deprecated** under the
27[feature lifecycle and deprecation policy](/community/feature-lifecycle):
27[feature lifecycle and deprecation policy](/community/feature-lifecycle.md):
2828the feature remains part of the specification, but is scheduled for removal.
2929Deprecated features document a migration path (or state that none is required)
3030and remain in the specification for at least twelve months, or at least
3131ninety days under the policy's
32[expedited-removal exception](/community/feature-lifecycle#expedited-removal),
32[expedited-removal exception](/community/feature-lifecycle.md#expedited-removal),
3333before they become eligible for removal, after which they may be **Removed**
3434in a future revision.
3535
from line 36
3636## Negotiation
3737
3838Version negotiation happens during
39[initialization](/specification/2025-06-18/basic/lifecycle#initialization). Clients and
39[initialization](/specification/2025-06-18/basic/lifecycle.md#initialization). Clients and
4040servers **MAY** support multiple protocol versions simultaneously, but they **MUST**
4141agree on a single version to use for the session.
4242
docs/2025-06-18/sdk Changed · +4 / -4 lines
from line 2
22
33> Official SDKs for building with Model Context Protocol
44
5Build MCP servers and clients using our official SDKs. SDKs are classified into tiers based on feature completeness, protocol support, and maintenance commitment. Learn more about [SDK tiers](/community/sdk-tiers).
5Build MCP servers and clients using our official SDKs. SDKs are classified into tiers based on feature completeness, protocol support, and maintenance commitment. Learn more about [SDK tiers](/community/sdk-tiers.md).
66
77## Available SDKs
88
from line 19
1919| [PHP](https://php.sdk.modelcontextprotocol.io) | [modelcontextprotocol/php-sdk](https://github.com/modelcontextprotocol/php-sdk) | Tier 3 |
2020| [Kotlin](https://kotlin.sdk.modelcontextprotocol.io) | [modelcontextprotocol/kotlin-sdk](https://github.com/modelcontextprotocol/kotlin-sdk) | Tier 3 |
2121
22See [SDK Tiering System](/community/sdk-tiers) for details on what each tier means.
22See [SDK Tiering System](/community/sdk-tiers.md) for details on what each tier means.
2323
2424## Getting Started
2525
from line 36
3636
3737Ready to start building with MCP? Choose your path:
3838
39> **[Build a Server](/docs/2025-06-18/develop/build-server)**
39> **[Build a Server](/docs/2025-06-18/develop/build-server.md)**
4040>
4141> Learn how to create your first MCP server
4242
43> **[Build a Client](/docs/2025-06-18/develop/build-client)**
43> **[Build a Client](/docs/2025-06-18/develop/build-client.md)**
4444>
4545> Create applications that connect to MCP servers
4646
docs/2025-06-18/tools/debugging Changed · +20 / -20 lines
from line 10
1010
1111MCP provides several tools for debugging at different levels:
1212
131. **[MCP Inspector](/docs/2025-06-18/tools/inspector)**: interactive, transport-agnostic
131. **[MCP Inspector](/docs/2025-06-18/tools/inspector.md)**: interactive, transport-agnostic
1414 testing UI. Connect to stdio or Streamable HTTP servers, invoke
15 [tools](/specification/2025-06-18/server/tools),
16 [prompts](/specification/2025-06-18/server/prompts), and
17 [resources](/specification/2025-06-18/server/resources), and watch the
15 [tools](/specification/2025-06-18/server/tools.md),
16 [prompts](/specification/2025-06-18/server/prompts.md), and
17 [resources](/specification/2025-06-18/server/resources.md), and watch the
1818 notification stream. This should be your first stop.
19192. **Server logging**: structured logs to stderr (stdio transport) or via
2020 [`notifications/message`](/specification/2025-06-18/server/utilities/logging#log-message-notifications)
from line 28
2828### Server-side logging
2929
3030When building a server that uses the local
31[stdio transport](/specification/2025-06-18/basic/transports#stdio), all messages
31[stdio transport](/specification/2025-06-18/basic/transports.md#stdio), all messages
3232logged to stderr (standard error) will be captured by the host application
3333automatically.
3434
from line 38
3838> will interfere with protocol operation.
3939
4040For servers using the
41[Streamable HTTP transport](/specification/2025-06-18/basic/transports#streamable-http),
41[Streamable HTTP transport](/specification/2025-06-18/basic/transports.md#streamable-http),
4242stderr is not captured by the client. Use the log message notifications below,
4343your own server-side log aggregation, or standard HTTP tooling (curl, browser
4444DevTools Network panel) to inspect requests,
from line 45
4545[`Mcp-Session-Id` headers](/specification/2025-06-18/basic/transports#session-management),
4646and SSE streams.
4747
48For all [transports](/specification/2025-06-18/basic/transports), you can also
48For all [transports](/specification/2025-06-18/basic/transports.md), you can also
4949provide logging to the client by sending a log message notification:
5050
5151```python Python theme={null}
from line 66
6666```
6767
6868MCP defines eight
69[RFC 5424 severity levels](/specification/2025-06-18/server/utilities/logging#log-levels)
69[RFC 5424 severity levels](/specification/2025-06-18/server/utilities/logging.md#log-levels)
7070(`debug` through `emergency`). Clients can adjust the minimum level at runtime
7171via the
7272[`logging/setLevel`](/specification/2025-06-18/server/utilities/logging#setting-log-level)
from line 164
164164
1651651. Check client logs
1661662. Verify server process is running
1673. Test standalone with [Inspector](/docs/2025-06-18/tools/inspector)
1673. Test standalone with [Inspector](/docs/2025-06-18/tools/inspector.md)
1681684. Verify
169 [protocol compatibility](/specification/2025-06-18/basic/lifecycle#version-negotiation)
169 [protocol compatibility](/specification/2025-06-18/basic/lifecycle.md#version-negotiation)
1701705. Check
171 [capability negotiation](/specification/2025-06-18/basic/lifecycle#capability-negotiation):
171 [capability negotiation](/specification/2025-06-18/basic/lifecycle.md#capability-negotiation):
172172 error [`-32602`](/specification/2025-06-18/basic/lifecycle#error-handling) is
173173 the standard JSON-RPC "Invalid params" code and is returned in many
174174 contexts. One common cause is a server sending
175 [sampling](/specification/2025-06-18/client/sampling) or
176 [elicitation](/specification/2025-06-18/client/elicitation) requests to a
175 [sampling](/specification/2025-06-18/client/sampling.md) or
176 [elicitation](/specification/2025-06-18/client/elicitation.md) requests to a
177177 client that hasn't declared that capability. Inspect the
178178 [`initialize` exchange](/specification/2025-06-18/basic/lifecycle#initialization)
179179 to verify both sides declared what you expect
from line 247
247247### Development cycle
248248
2492491. Initial Development
250 * Use [Inspector](/docs/2025-06-18/tools/inspector) for basic testing
250 * Use [Inspector](/docs/2025-06-18/tools/inspector.md) for basic testing
251251 * Implement core functionality
252252 * Add logging points
253253
from line 263
263263* **Configuration changes**: Restart the MCP client
264264* **Server code changes**: Restart the client (for Claude Desktop, fully quit
265265 and reopen; closing the window is not enough)
266* **Quick iteration**: Use [Inspector](/docs/2025-06-18/tools/inspector) during
266* **Quick iteration**: Use [Inspector](/docs/2025-06-18/tools/inspector.md) during
267267 development
268268
269269## Best practices
from line 303
303303 * Monitor access patterns
304304
305305For a full treatment of MCP attack vectors and mitigations, see
306[Security Best Practices](/docs/2025-06-18/tutorials/security/security_best_practices).
306[Security Best Practices](/docs/2025-06-18/tutorials/security/security_best_practices.md).
307307
308308## Getting help
309309
from line 311
311311
3123121. **First Steps**
313313 * Check server logs
314 * Test with [Inspector](/docs/2025-06-18/tools/inspector)
314 * Test with [Inspector](/docs/2025-06-18/tools/inspector.md)
315315 * Review configuration
316316 * Verify environment
317317
from line 327
327327
328328## Next steps
329329
330> **[MCP Inspector](/docs/2025-06-18/tools/inspector)**
330> **[MCP Inspector](/docs/2025-06-18/tools/inspector.md)**
331331>
332332> Learn to use the MCP Inspector
333333
334> **[Build an MCP server](/docs/2025-06-18/develop/build-server)**
334> **[Build an MCP server](/docs/2025-06-18/develop/build-server.md)**
335335>
336336> Walk through building a server from scratch
337337
338> **[Connect local servers](/docs/2025-06-18/develop/connect-local-servers)**
338> **[Connect local servers](/docs/2025-06-18/develop/connect-local-servers.md)**
339339>
340340> Full claude\_desktop\_config.json reference and troubleshooting
341341
docs/2025-06-18/tools/inspector Changed · +5 / -3 lines
from line 2
22
33> In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers
44
5The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](/docs/2025-06-18/tools/debugging) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.
5The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](/docs/2025-06-18/tools/debugging.md) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.
66
77## Getting started
88
from line 66
6666
6767
6868
69The MCP Inspector interface
70
6971The Inspector provides several features for interacting with your MCP server:
7072
7173### Server connection pane
7274
73* Allows selecting the [transport](/specification/2025-06-18/basic/transports) for connecting to the server
75* Allows selecting the [transport](/specification/2025-06-18/basic/transports.md) for connecting to the server
7476* For local servers, supports customizing the command-line arguments and environment
7577
7678### Resources tab
from line 129
127129>
128130> Check out the MCP Inspector source code
129131
130> **[Debugging Guide](/docs/2025-06-18/tools/debugging)**
132> **[Debugging Guide](/docs/2025-06-18/tools/debugging.md)**
131133>
132134> Learn about broader debugging strategies
133135
docs/2025-06-18/tutorials/security/authorization Changed · +7 / -7 lines
from line 4
44
55Authorization in the Model Context Protocol (MCP) secures access to sensitive resources and operations exposed by MCP servers. If your MCP server handles user data or administrative actions, authorization ensures only permitted users can access its endpoints.
66
7MCP uses standardized authorization flows to build trust between MCP clients and MCP servers. Its design doesn't focus on one specific authorization or identity system, but rather follows the conventions outlined for [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13). For detailed information, see the [Authorization specification](/specification/2025-06-18/basic/authorization).
7MCP uses standardized authorization flows to build trust between MCP clients and MCP servers. Its design doesn't focus on one specific authorization or identity system, but rather follows the conventions outlined for [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13). For detailed information, see the [Authorization specification](/specification/2025-06-18/basic/authorization.md).
88
99## When Should You Use Authorization?
1010
from line 20
2020>
2121> **Authorization for Local MCP Servers**
2222>
23> For MCP servers using the [STDIO transport](/specification/2025-06-18/basic/transports#stdio), you can use environment-based credentials or credentials provided by third-party libraries embedded directly in the MCP server instead. Because a STDIO-built MCP server runs locally, it has access to a range of flexible options when it comes to acquiring user credentials that may or may not rely on in-browser authentication and authorization flows.
23> For MCP servers using the [STDIO transport](/specification/2025-06-18/basic/transports.md#stdio), you can use environment-based credentials or credentials provided by third-party libraries embedded directly in the MCP server instead. Because a STDIO-built MCP server runs locally, it has access to a range of flexible options when it comes to acquiring user credentials that may or may not rely on in-browser authentication and authorization flows.
2424>
2525> OAuth flows, in turn, are designed for HTTP-based transports where the MCP server is remotely-hosted and the client uses OAuth to establish that a user is authorized to access said remote server.
2626
from line 242
242242
243243### MCP Server Setup
244244
245We will now set up our MCP server to use the locally-running Keycloak authorization server. Depending on your programming language preference, you can use one of the supported [MCP SDKs](/docs/2025-06-18/sdk).
245We will now set up our MCP server to use the locally-running Keycloak authorization server. Depending on your programming language preference, you can use one of the supported [MCP SDKs](/docs/2025-06-18/sdk.md).
246246
247247For our testing purposes, we will create an extremely simple MCP server that exposes two tools - one for addition and another for multiplication. The server will require authorization to access these.
248248
from line 1001
10011001
10021002## Common Pitfalls and How to Avoid Them
10031003
1004For comprehensive security guidance, including attack vectors, mitigation strategies, and implementation best practices, make sure to read through [Security Best Practices](/docs/2025-06-18/tutorials/security/security_best_practices). A few key issues are called out below.
1004For comprehensive security guidance, including attack vectors, mitigation strategies, and implementation best practices, make sure to read through [Security Best Practices](/docs/2025-06-18/tutorials/security/security_best_practices.md). A few key issues are called out below.
10051005
10061006* **Do not implement token validation or authorization logic by yourself**. Use off-the-shelf, well-tested, and secure libraries for things like token validation or authorization decisions. Doing everything from scratch means that you're more likely to implement things incorrectly unless you are a security expert.
10071007* **Use short-lived access tokens**. Depending on the authorization server used, this setting might be customizable. We recommend to not use long-lived tokens - if a malicious actor steals them, they will be able to maintain their access for longer periods.
from line 1030
10301030
10311031For additional details, refer to:
10321032
1033* [Authorization Specification](/specification/2025-06-18/basic/authorization)
1034* [Security Best Practices](/docs/2025-06-18/tutorials/security/security_best_practices)
1035* [Available MCP SDKs](/docs/2025-06-18/sdk)
1033* [Authorization Specification](/specification/2025-06-18/basic/authorization.md)
1034* [Security Best Practices](/docs/2025-06-18/tutorials/security/security_best_practices.md)
1035* [Available MCP SDKs](/docs/2025-06-18/sdk.md)
10361036
10371037Understanding these standards will help you implement authorization correctly and troubleshoot issues when they arise.
10381038
docs/2025-06-18/tutorials/security/security_best_practices Changed · +4 / -4 lines
from line 8
88
99This document provides security considerations for the Model Context
1010Protocol (MCP), complementing the
11[MCP Authorization](/specification/2025-06-18/basic/authorization)
11[MCP Authorization](/specification/2025-06-18/basic/authorization.md)
1212specification. This document identifies security risks, attack vectors,
1313and best practices specific to MCP implementations.
1414
from line 148
148148 consent screen
1491496. The MCP authorization code is redirected to the attacker's server
150150 (specified in the malicious `redirect_uri` parameter during
151 [dynamic client registration](/specification/2025-06-18/basic/authorization#dynamic-client-registration))
151 [dynamic client registration](/specification/2025-06-18/basic/authorization.md#dynamic-client-registration))
1521527. The attacker exchanges the stolen authorization code for access
153153 tokens for the MCP server without the user's explicit approval
1541548. The attacker now has access to the third-party API as the compromised
from line 284
284284#### Risks
285285
286286Token passthrough is explicitly forbidden in the
287[authorization specification](/specification/2025-06-18/basic/authorization)
287[authorization specification](/specification/2025-06-18/basic/authorization.md)
288288as it introduces a number of security risks, that include:
289289
290290* **Security Control Circumvention**
from line 538
5385382. The attacker obtains an existing session ID and sends a malicious
539539 event to **Server B** with said session ID.
540540 * When a server supports
541 [redelivery/resumable streams](/specification/2025-06-18/basic/transports#resumability-and-redelivery),
541 [redelivery/resumable streams](/specification/2025-06-18/basic/transports.md#resumability-and-redelivery),
542542 deliberately terminating the request before receiving the response
543543 could lead to it being resumed by the original client via the GET
544544 request for server sent events.
docs/2025-11-25/develop/build-client Changed · +4 / -4 lines
from line 4
44
55In this tutorial, you'll learn how to build an LLM-powered chatbot client that connects to MCP servers.
66
7Before you begin, it helps to have gone through our [Build an MCP Server](/docs/2025-11-25/develop/build-server) tutorial so you can understand how clients and servers communicate.
7Before you begin, it helps to have gone through our [Build an MCP Server](/docs/2025-11-25/develop/build-server.md) tutorial so you can understand how clients and servers communicate.
88
99**Python**
1010
from line 381
381381 * Be cautious with tool permissions
382382
3833834. **Tool Names**
384 * Tool names can be validated according to the format specified [here](/specification/2025-11-25/server/tools#tool-names)
384 * Tool names can be validated according to the format specified [here](/specification/2025-11-25/server/tools.md#tool-names)
385385 * If a tool name conforms to the specified format, it should not fail validation by an MCP client
386386
387387## Troubleshooting
from line 1981
19811981 * Be cautious with tool permissions
19821982
198319834. **Tool Names**
1984 * Tool names can be validated according to the format specified [here](/specification/2025-11-25/server/tools#tool-names)
1984 * Tool names can be validated according to the format specified [here](/specification/2025-11-25/server/tools.md#tool-names)
19851985 * If a tool name conforms to the specified format, it should not fail validation by an MCP client
19861986
19871987## Troubleshooting
from line 2497
24972497
24982498## Next steps
24992499
2500> **[Example servers](/examples)**
2500> **[Example servers](/examples.md)**
25012501>
25022502> Check out our gallery of official MCP servers and implementations
25032503
docs/2025-11-25/develop/build-server Changed · +17 / -17 lines
from line 12
1212
1313> [!NOTE]
1414>
15> Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have a guide on [building your own client](/docs/2025-11-25/develop/build-client).
15> Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have a guide on [building your own client](/docs/2025-11-25/develop/build-client.md).
1616
1717### Core MCP Concepts
1818
1919MCP servers can provide three main types of capabilities:
2020
211. **[Resources](/docs/2025-11-25/learn/server-concepts#resources)**: File-like data that can be read by clients (like API responses or file contents)
222. **[Tools](/docs/2025-11-25/learn/server-concepts#tools)**: Functions that can be called by the LLM (with user approval)
233. **[Prompts](/docs/2025-11-25/learn/server-concepts#prompts)**: Pre-written templates that help users accomplish specific tasks
211. **[Resources](/docs/2025-11-25/learn/server-concepts.md#resources)**: File-like data that can be read by clients (like API responses or file contents)
222. **[Tools](/docs/2025-11-25/learn/server-concepts.md#tools)**: Functions that can be called by the LLM (with user approval)
233. **[Prompts](/docs/2025-11-25/learn/server-concepts.md#prompts)**: Pre-written templates that help users accomplish specific tasks
2424
2525This tutorial will primarily focus on tools.
2626
from line 253
253253
254254> [!NOTE]
255255>
256> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client) tutorial to build an MCP client that connects to the server we just built.
256> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client.md) tutorial to build an MCP client that connects to the server we just built.
257257
258258First, make sure you have Claude for Desktop installed. [You can install the latest version
259259here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
from line 717
717717
718718> [!NOTE]
719719>
720> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client) tutorial to build an MCP client that connects to the server we just built.
720> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client.md) tutorial to build an MCP client that connects to the server we just built.
721721
722722First, make sure you have Claude for Desktop installed. [You can install the latest version
723723here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
from line 1358
13581358
13591359> [!NOTE]
13601360>
1361> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client) tutorial to build an MCP client that connects to the server we just built.
1361> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client.md) tutorial to build an MCP client that connects to the server we just built.
13621362
13631363First, make sure you have Claude for Desktop installed. [You can install the latest version
13641364here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
from line 1615
16151615
16161616> [!NOTE]
16171617>
1618> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client) tutorial to build an MCP client that connects to the server we just built.
1618> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client.md) tutorial to build an MCP client that connects to the server we just built.
16191619
16201620First, make sure you have Claude for Desktop installed. [You can install the latest version
16211621here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
from line 1909
19091909
19101910> [!NOTE]
19111911>
1912> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client) tutorial to build an MCP client that connects to the server we just built.
1912> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client.md) tutorial to build an MCP client that connects to the server we just built.
19131913
19141914First, make sure you have Claude for Desktop installed. [You can install the latest version here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
19151915
from line 2325
23252325
23262326> [!NOTE]
23272327>
2328> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client) tutorial to build an MCP client that connects to the server we just built.
2328> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client.md) tutorial to build an MCP client that connects to the server we just built.
23292329
23302330First, make sure you have Claude for Desktop installed. [You can install the latest version here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
23312331
from line 2752
27522752
27532753> [!NOTE]
27542754>
2755> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client) tutorial to build an MCP client that connects to the server we just built.
2755> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/2025-11-25/develop/build-client.md) tutorial to build an MCP client that connects to the server we just built.
27562756
27572757First, make sure you have Claude for Desktop installed. [You can install the latest version here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
27582758
from line 2884
28842884>
28852885> **None of this is working. What do I do?**
28862886>
2887> Please refer to our [debugging guide](/docs/2025-11-25/tools/debugging) for better debugging tools and more detailed guidance.
2887> Please refer to our [debugging guide](/docs/2025-11-25/tools/debugging.md) for better debugging tools and more detailed guidance.
28882888
28892889> **Weather API Issues**
28902890>
from line 2908
29082908
29092909> [!NOTE]
29102910>
2911> For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/2025-11-25/tools/debugging)
2911> For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/2025-11-25/tools/debugging.md)
29122912
29132913## Next steps
29142914
2915> **[Building a client](/docs/2025-11-25/develop/build-client)**
2915> **[Building a client](/docs/2025-11-25/develop/build-client.md)**
29162916>
29172917> Learn how to build your own MCP client that can connect to your server
29182918
2919> **[Example servers](/examples)**
2919> **[Example servers](/examples.md)**
29202920>
29212921> Check out our gallery of official MCP servers and implementations
29222922
2923> **[Debugging Guide](/docs/2025-11-25/tools/debugging)**
2923> **[Debugging Guide](/docs/2025-11-25/tools/debugging.md)**
29242924>
29252925> Learn how to effectively debug MCP servers and integrations
29262926
2927> **[Build with Agent Skills](/docs/2025-11-25/develop/build-with-agent-skills)**
2927> **[Build with Agent Skills](/docs/2025-11-25/develop/build-with-agent-skills.md)**
29282928>
29292929> Use agent skills to guide AI coding assistants through server design
29302930
docs/2025-11-25/develop/build-with-agent-skills Changed · +8 / -8 lines
from line 47
4747* **Who will use it** — just you, your team, or anyone who installs it
4848* **Action surface size** — a handful of operations versus wrapping a large API
4949* **User interaction needs** — plain text results, structured input via
50 [elicitation](/specification/2025-11-25/client/elicitation), or rich UI widgets
50 [elicitation](/specification/2025-11-25/client/elicitation.md), or rich UI widgets
5151* **Upstream auth** — API keys, OAuth 2.0, or none
5252
5353If your opening message already covers these, the agent skips ahead to the
from line 58
5858Based on discovery, the skill recommends one of four paths and scaffolds
5959accordingly:
6060
61**Remote [Streamable HTTP](/specification/2025-11-25/basic/transports#streamable-http)**
61**Remote [Streamable HTTP](/specification/2025-11-25/basic/transports.md#streamable-http)**
6262is the default for anything wrapping a cloud API. Zero install friction, one
6363deployment serves all users, and OAuth flows work properly because the server
6464can handle redirects and token storage. The reference skill includes scaffolds
6565for Cloudflare Workers and portable Express/FastMCP setups.
6666
67**[MCP apps](/extensions/apps/overview)** extend a server with interactive
67**[MCP apps](/extensions/apps/overview.md)** extend a server with interactive
6868widgets rendered in chat, such as searchable pickers, charts, and live
6969dashboards. The skill hands off to `build-mcp-app` when
70[elicitation's](/specification/2025-11-25/client/elicitation) flat-form constraints
70[elicitation's](/specification/2025-11-25/client/elicitation.md) flat-form constraints
7171don't fit.
7272
7373**[MCP Bundles (MCPB)](https://github.com/modelcontextprotocol/mcpb)** package a
from line 76
7676must touch the user's machine: reading local files, driving desktop apps, or
7777talking to localhost services. The skill hands off to `build-mcpb`.
7878
79**Local [stdio](/specification/2025-11-25/basic/transports#stdio)** remains available
79**Local [stdio](/specification/2025-11-25/basic/transports.md#stdio)** remains available
8080for prototyping, with a noted upgrade path to MCPB when you're ready to
8181distribute.
8282
from line 85
8585Once your agent scaffolds the server, iterate on tool descriptions and error
8686handling, then test and ship:
8787
88> **[MCP Inspector](/docs/2025-11-25/tools/inspector)**
88> **[MCP Inspector](/docs/2025-11-25/tools/inspector.md)**
8989>
9090> Test your server's tools, resources, and prompts interactively
9191
92> **[Connect to a client](/docs/2025-11-25/develop/connect-local-servers)**
92> **[Connect to a client](/docs/2025-11-25/develop/connect-local-servers.md)**
9393>
9494> Wire your server into an MCP client via local or remote configuration
9595
96> **[Publish to the Registry](/registry/quickstart)**
96> **[Publish to the Registry](/registry/quickstart.md)**
9797>
9898> Make your server discoverable in the MCP Registry
9999
docs/2025-11-25/develop/connect-local-servers Changed · +4 / -4 lines
from line 204
204204
205205> **None of this is working. What do I do?**
206206>
207> Please refer to our [debugging guide](/docs/2025-11-25/tools/debugging) for better debugging tools and more detailed guidance.
207> Please refer to our [debugging guide](/docs/2025-11-25/tools/debugging.md) for better debugging tools and more detailed guidance.
208208
209209> **ENOENT error and `$\{APPDATA\}` in paths on Windows**
210210>
from line 244
244244> Browse our collection of official and community-created MCP servers for
245245> additional capabilities
246246
247> **[Build your own server](/docs/2025-11-25/develop/build-server)**
247> **[Build your own server](/docs/2025-11-25/develop/build-server.md)**
248248>
249249> Create custom MCP servers tailored to your specific workflows and
250250> integrations
251251
252> **[Connect to remote servers](/docs/2025-11-25/develop/connect-remote-servers)**
252> **[Connect to remote servers](/docs/2025-11-25/develop/connect-remote-servers.md)**
253253>
254254> Learn how to connect Claude to remote MCP servers for cloud-based tools and
255255> services
256256
257> **[Understand the protocol](/docs/2025-11-25/learn/architecture)**
257> **[Understand the protocol](/docs/2025-11-25/learn/architecture.md)**
258258>
259259> Dive deeper into how MCP works and its architecture
260260
docs/2025-11-25/develop/connect-remote-servers Changed · +4 / -4 lines
from line 19
1919With Custom Connectors, you can:
2020
2121* [Connect Claude to existing remote MCP servers](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) provided by third-party developers
22* [Build your own remote MCP servers to connect with any tool](/docs/2025-11-25/develop/build-server)
22* [Build your own remote MCP servers to connect with any tool](/docs/2025-11-25/develop/build-server.md)
2323
2424## Connecting to a Remote MCP Server
2525
from line 81
8181
8282Now that you've connected Claude to a remote MCP server, you can explore its capabilities in your conversations. Try using the connected tools to automate tasks, access external data, or integrate with your existing workflows.
8383
84> **[Build your own remote server](/docs/2025-11-25/develop/build-server)**
84> **[Build your own remote server](/docs/2025-11-25/develop/build-server.md)**
8585>
8686> Create custom remote MCP servers to integrate with proprietary tools and
8787> services
from line 90
9090>
9191> Browse our collection of official and community-created MCP servers
9292
93> **[Connect local servers](/docs/2025-11-25/develop/connect-local-servers)**
93> **[Connect local servers](/docs/2025-11-25/develop/connect-local-servers.md)**
9494>
9595> Learn how to connect Claude Desktop to local MCP servers for direct system
9696> access
9797
98> **[Understand the architecture](/docs/2025-11-25/learn/architecture)**
98> **[Understand the architecture](/docs/2025-11-25/learn/architecture.md)**
9999>
100100> Dive deeper into how MCP works and its architecture
101101
docs/2025-11-25/getting-started/intro Changed · +6 / -6 lines
from line 29
2929
3030## Start Building
3131
32> **[Build servers](/docs/2025-11-25/develop/build-server)**
32> **[Build servers](/docs/2025-11-25/develop/build-server.md)**
3333>
3434> Create MCP servers to expose your data and tools
3535
36> **[Build clients](/docs/2025-11-25/develop/build-client)**
36> **[Build clients](/docs/2025-11-25/develop/build-client.md)**
3737>
3838> Develop applications that connect to MCP servers
3939
40> **[Build MCP Apps](/extensions/apps/overview)**
40> **[Build MCP Apps](/extensions/apps/overview.md)**
4141>
4242> Build interactive apps that run inside AI clients
4343
4444## Learn more
4545
46> **[Architecture](/docs/2025-11-25/learn/architecture)**
46> **[Architecture](/docs/2025-11-25/learn/architecture.md)**
4747>
4848> Learn the core concepts and architecture of MCP
4949
50> **[Security](/docs/2025-11-25/tutorials/security/security_best_practices)**
50> **[Security](/docs/2025-11-25/tutorials/security/security_best_practices.md)**
5151>
5252> Understand the security considerations and best practices for MCP
5353
5454## Community
5555
56> **[Contributing](/community/contributing)**
56> **[Contributing](/community/contributing.md)**
5757>
5858> Learn how to get involved and contribute to MCP
5959
docs/2025-11-25/learn/architecture Changed · +6 / -6 lines
from line 4
44
55Because MCP SDKs abstract away many concerns, most developers will likely find the [data layer protocol](#data-layer-protocol) section to be the most useful. It discusses how MCP servers can provide context to an AI application.
66
7For specific implementation details, please refer to the documentation for your [language-specific SDK](/docs/2025-11-25/sdk).
7For specific implementation details, please refer to the documentation for your [language-specific SDK](/docs/2025-11-25/sdk.md).
88
99## Scope
1010
1111The Model Context Protocol includes the following projects:
1212
13* [MCP Specification](https://modelcontextprotocol.io/specification/latest): A specification of MCP that outlines the implementation requirements for clients and servers.
14* [MCP SDKs](/docs/2025-11-25/sdk): SDKs for different programming languages that implement MCP.
13* [MCP Specification](https://modelcontextprotocol.io/specification/latest.md): A specification of MCP that outlines the implementation requirements for clients and servers.
14* [MCP SDKs](/docs/2025-11-25/sdk.md): SDKs for different programming languages that implement MCP.
1515* **MCP Development Tools**: Tools for developing MCP servers and clients, including the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
1616* [MCP Reference Server Implementations](https://github.com/modelcontextprotocol/servers): Reference implementations of MCP servers.
1717
from line 104
104104
105105#### Lifecycle management
106106
107MCP is a stateful protocol (A subset of MCP can be made stateless using the Streamable HTTP transport) that requires lifecycle management. The purpose of lifecycle management is to negotiate the capabilities (Features and operations that a client or server supports, such as tools, resources, or prompts) that both client and server support. Detailed information can be found in the [specification](/specification/2025-11-25/basic/lifecycle), and the [example](#example) showcases the initialization sequence.
107MCP is a stateful protocol (A subset of MCP can be made stateless using the Streamable HTTP transport) that requires lifecycle management. The purpose of lifecycle management is to negotiate the capabilities (Features and operations that a client or server supports, such as tools, resources, or prompts) that both client and server support. Detailed information can be found in the [specification](/specification/2025-11-25/basic/lifecycle.md), and the [example](#example) showcases the initialization sequence.
108108
109109#### Primitives
110110
from line 121
121121
122122As a concrete example, consider an MCP server that provides context about a database. It can expose tools for querying the database, a resource that contains the schema of the database, and a prompt that includes few-shot examples for interacting with the tools.
123123
124For more details about server primitives see [server concepts](./server-concepts).
124For more details about server primitives see [server concepts](/docs/2025-11-25/learn/server-concepts.md).
125125
126126MCP also defines primitives that *clients* can expose. These primitives allow MCP server authors to build richer interactions.
127127
from line 129
129129* **Elicitation**: Allows servers to request additional information from users. This is useful when server authors want to get more information from the user, or ask for confirmation of an action. They can use the `elicitation/create` method to request additional information from the user.
130130* **Logging**: Enables servers to send log messages to clients for debugging and monitoring purposes.
131131
132For more details about client primitives see [client concepts](./client-concepts).
132For more details about client primitives see [client concepts](/docs/2025-11-25/learn/client-concepts.md).
133133
134134Besides server and client primitives, the protocol offers cross-cutting utility primitives that augment how requests are executed:
135135
docs/2025-11-25/learn/versioning Changed · +4 / -4 lines
from line 18
1818 receive backwards compatible changes.
1919* **Final**: past, complete specifications that will not be changed.
2020
21The **current** protocol version is [**2025-11-25**](/specification/2025-11-25/).
21The **current** protocol version is [**2025-11-25**](/specification/2025-11-25.md).
2222
2323## Feature States
2424
2525Individual features of the specification may additionally be marked as
2626**Deprecated** under the
27[feature lifecycle and deprecation policy](/community/feature-lifecycle):
27[feature lifecycle and deprecation policy](/community/feature-lifecycle.md):
2828the feature remains part of the specification, but is scheduled for removal.
2929Deprecated features document a migration path (or state that none is required)
3030and remain in the specification for at least twelve months, or at least
3131ninety days under the policy's
32[expedited-removal exception](/community/feature-lifecycle#expedited-removal),
32[expedited-removal exception](/community/feature-lifecycle.md#expedited-removal),
3333before they become eligible for removal, after which they may be **Removed**
3434in a future revision.
3535
from line 36
3636## Negotiation
3737
3838Version negotiation happens during
39[initialization](/specification/2025-11-25/basic/lifecycle#initialization). Clients and
39[initialization](/specification/2025-11-25/basic/lifecycle.md#initialization). Clients and
4040servers **MAY** support multiple protocol versions simultaneously, but they **MUST**
4141agree on a single version to use for the session.
4242
docs/2025-11-25/sdk Changed · +4 / -4 lines
from line 2
22
33> Official SDKs for building with Model Context Protocol
44
5Build MCP servers and clients using our official SDKs. SDKs are classified into tiers based on feature completeness, protocol support, and maintenance commitment. Learn more about [SDK tiers](/community/sdk-tiers).
5Build MCP servers and clients using our official SDKs. SDKs are classified into tiers based on feature completeness, protocol support, and maintenance commitment. Learn more about [SDK tiers](/community/sdk-tiers.md).
66
77## Available SDKs
88
from line 19
1919| [PHP](https://php.sdk.modelcontextprotocol.io) | [modelcontextprotocol/php-sdk](https://github.com/modelcontextprotocol/php-sdk) | Tier 3 |
2020| [Kotlin](https://kotlin.sdk.modelcontextprotocol.io) | [modelcontextprotocol/kotlin-sdk](https://github.com/modelcontextprotocol/kotlin-sdk) | Tier 3 |
2121
22See [SDK Tiering System](/community/sdk-tiers) for details on what each tier means.
22See [SDK Tiering System](/community/sdk-tiers.md) for details on what each tier means.
2323
2424## Getting Started
2525
from line 36
3636
3737Ready to start building with MCP? Choose your path:
3838
39> **[Build a Server](/docs/2025-11-25/develop/build-server)**
39> **[Build a Server](/docs/2025-11-25/develop/build-server.md)**
4040>
4141> Learn how to create your first MCP server
4242
43> **[Build a Client](/docs/2025-11-25/develop/build-client)**
43> **[Build a Client](/docs/2025-11-25/develop/build-client.md)**
4444>
4545> Create applications that connect to MCP servers
4646
docs/2025-11-25/tools/debugging Changed · +20 / -20 lines
from line 10
1010
1111MCP provides several tools for debugging at different levels:
1212
131. **[MCP Inspector](/docs/2025-11-25/tools/inspector)**: interactive, transport-agnostic
131. **[MCP Inspector](/docs/2025-11-25/tools/inspector.md)**: interactive, transport-agnostic
1414 testing UI. Connect to stdio or Streamable HTTP servers, invoke
15 [tools](/specification/2025-11-25/server/tools),
16 [prompts](/specification/2025-11-25/server/prompts), and
17 [resources](/specification/2025-11-25/server/resources), and watch the
15 [tools](/specification/2025-11-25/server/tools.md),
16 [prompts](/specification/2025-11-25/server/prompts.md), and
17 [resources](/specification/2025-11-25/server/resources.md), and watch the
1818 notification stream. This should be your first stop.
19192. **Server logging**: structured logs to stderr (stdio transport) or via
2020 [`notifications/message`](/specification/2025-11-25/server/utilities/logging#log-message-notifications)
from line 28
2828### Server-side logging
2929
3030When building a server that uses the local
31[stdio transport](/specification/2025-11-25/basic/transports#stdio), all messages
31[stdio transport](/specification/2025-11-25/basic/transports.md#stdio), all messages
3232logged to stderr (standard error) will be captured by the host application
3333automatically.
3434
from line 38
3838> will interfere with protocol operation.
3939
4040For servers using the
41[Streamable HTTP transport](/specification/2025-11-25/basic/transports#streamable-http),
41[Streamable HTTP transport](/specification/2025-11-25/basic/transports.md#streamable-http),
4242stderr is not captured by the client. Use the log message notifications below,
4343your own server-side log aggregation, or standard HTTP tooling (curl, browser
4444DevTools Network panel) to inspect requests,
from line 45
4545[`Mcp-Session-Id` headers](/specification/2025-11-25/basic/transports#session-management),
4646and SSE streams.
4747
48For all [transports](/specification/2025-11-25/basic/transports), you can also
48For all [transports](/specification/2025-11-25/basic/transports.md), you can also
4949provide logging to the client by sending a log message notification:
5050
5151```python Python theme={null}
from line 66
6666```
6767
6868MCP defines eight
69[RFC 5424 severity levels](/specification/2025-11-25/server/utilities/logging#log-levels)
69[RFC 5424 severity levels](/specification/2025-11-25/server/utilities/logging.md#log-levels)
7070(`debug` through `emergency`). Clients can adjust the minimum level at runtime
7171via the
7272[`logging/setLevel`](/specification/2025-11-25/server/utilities/logging#setting-log-level)
from line 164
164164
1651651. Check client logs
1661662. Verify server process is running
1673. Test standalone with [Inspector](/docs/2025-11-25/tools/inspector)
1673. Test standalone with [Inspector](/docs/2025-11-25/tools/inspector.md)
1681684. Verify
169 [protocol compatibility](/specification/2025-11-25/basic/lifecycle#version-negotiation)
169 [protocol compatibility](/specification/2025-11-25/basic/lifecycle.md#version-negotiation)
1701705. Check
171 [capability negotiation](/specification/2025-11-25/basic/lifecycle#capability-negotiation):
171 [capability negotiation](/specification/2025-11-25/basic/lifecycle.md#capability-negotiation):
172172 error [`-32602`](/specification/2025-11-25/basic/lifecycle#error-handling) is
173173 the standard JSON-RPC "Invalid params" code and is returned in many
174174 contexts. One common cause is a server sending
175 [sampling](/specification/2025-11-25/client/sampling) or
176 [elicitation](/specification/2025-11-25/client/elicitation) requests to a
175 [sampling](/specification/2025-11-25/client/sampling.md) or
176 [elicitation](/specification/2025-11-25/client/elicitation.md) requests to a
177177 client that hasn't declared that capability. Inspect the
178178 [`initialize` exchange](/specification/2025-11-25/basic/lifecycle#initialization)
179179 to verify both sides declared what you expect
from line 247
247247### Development cycle
248248
2492491. Initial Development
250 * Use [Inspector](/docs/2025-11-25/tools/inspector) for basic testing
250 * Use [Inspector](/docs/2025-11-25/tools/inspector.md) for basic testing
251251 * Implement core functionality
252252 * Add logging points
253253
from line 263
263263* **Configuration changes**: Restart the MCP client
264264* **Server code changes**: Restart the client (for Claude Desktop, fully quit
265265 and reopen; closing the window is not enough)
266* **Quick iteration**: Use [Inspector](/docs/2025-11-25/tools/inspector) during
266* **Quick iteration**: Use [Inspector](/docs/2025-11-25/tools/inspector.md) during
267267 development
268268
269269## Best practices
from line 303
303303 * Monitor access patterns
304304
305305For a full treatment of MCP attack vectors and mitigations, see
306[Security Best Practices](/docs/2025-11-25/tutorials/security/security_best_practices).
306[Security Best Practices](/docs/2025-11-25/tutorials/security/security_best_practices.md).
307307
308308## Getting help
309309
from line 311
311311
3123121. **First Steps**
313313 * Check server logs
314 * Test with [Inspector](/docs/2025-11-25/tools/inspector)
314 * Test with [Inspector](/docs/2025-11-25/tools/inspector.md)
315315 * Review configuration
316316 * Verify environment
317317
from line 327
327327
328328## Next steps
329329
330> **[MCP Inspector](/docs/2025-11-25/tools/inspector)**
330> **[MCP Inspector](/docs/2025-11-25/tools/inspector.md)**
331331>
332332> Learn to use the MCP Inspector
333333
334> **[Build an MCP server](/docs/2025-11-25/develop/build-server)**
334> **[Build an MCP server](/docs/2025-11-25/develop/build-server.md)**
335335>
336336> Walk through building a server from scratch
337337
338> **[Connect local servers](/docs/2025-11-25/develop/connect-local-servers)**
338> **[Connect local servers](/docs/2025-11-25/develop/connect-local-servers.md)**
339339>
340340> Full claude\_desktop\_config.json reference and troubleshooting
341341
docs/2025-11-25/tools/inspector Changed · +5 / -3 lines
from line 2
22
33> In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers
44
5The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](/docs/2025-11-25/tools/debugging) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.
5The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](/docs/2025-11-25/tools/debugging.md) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.
66
77## Getting started
88
from line 66
6666
6767
6868
69The MCP Inspector interface
70
6971The Inspector provides several features for interacting with your MCP server:
7072
7173### Server connection pane
7274
73* Allows selecting the [transport](/specification/2025-11-25/basic/transports) for connecting to the server
75* Allows selecting the [transport](/specification/2025-11-25/basic/transports.md) for connecting to the server
7476* For local servers, supports customizing the command-line arguments and environment
7577
7678### Resources tab
from line 129
127129>
128130> Check out the MCP Inspector source code
129131
130> **[Debugging Guide](/docs/2025-11-25/tools/debugging)**
132> **[Debugging Guide](/docs/2025-11-25/tools/debugging.md)**
131133>
132134> Learn about broader debugging strategies
133135
docs/2025-11-25/tutorials/security/authorization Changed · +7 / -7 lines
from line 4
44
55Authorization in the Model Context Protocol (MCP) secures access to sensitive resources and operations exposed by MCP servers. If your MCP server handles user data or administrative actions, authorization ensures only permitted users can access its endpoints.
66
7MCP uses standardized authorization flows to build trust between MCP clients and MCP servers. Its design doesn't focus on one specific authorization or identity system, but rather follows the conventions outlined for [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13). For detailed information, see the [Authorization specification](/specification/2025-11-25/basic/authorization).
7MCP uses standardized authorization flows to build trust between MCP clients and MCP servers. Its design doesn't focus on one specific authorization or identity system, but rather follows the conventions outlined for [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13). For detailed information, see the [Authorization specification](/specification/2025-11-25/basic/authorization.md).
88
99## When Should You Use Authorization?
1010
from line 20
2020>
2121> **Authorization for Local MCP Servers**
2222>
23> For MCP servers using the [STDIO transport](/specification/2025-11-25/basic/transports#stdio), you can use environment-based credentials or credentials provided by third-party libraries embedded directly in the MCP server instead. Because a STDIO-built MCP server runs locally, it has access to a range of flexible options when it comes to acquiring user credentials that may or may not rely on in-browser authentication and authorization flows.
23> For MCP servers using the [STDIO transport](/specification/2025-11-25/basic/transports.md#stdio), you can use environment-based credentials or credentials provided by third-party libraries embedded directly in the MCP server instead. Because a STDIO-built MCP server runs locally, it has access to a range of flexible options when it comes to acquiring user credentials that may or may not rely on in-browser authentication and authorization flows.
2424>
2525> OAuth flows, in turn, are designed for HTTP-based transports where the MCP server is remotely-hosted and the client uses OAuth to establish that a user is authorized to access said remote server.
2626
from line 242
242242
243243### MCP Server Setup
244244
245We will now set up our MCP server to use the locally-running Keycloak authorization server. Depending on your programming language preference, you can use one of the supported [MCP SDKs](/docs/2025-11-25/sdk).
245We will now set up our MCP server to use the locally-running Keycloak authorization server. Depending on your programming language preference, you can use one of the supported [MCP SDKs](/docs/2025-11-25/sdk.md).
246246
247247For our testing purposes, we will create an extremely simple MCP server that exposes two tools - one for addition and another for multiplication. The server will require authorization to access these.
248248
from line 1001
10011001
10021002## Common Pitfalls and How to Avoid Them
10031003
1004For comprehensive security guidance, including attack vectors, mitigation strategies, and implementation best practices, make sure to read through [Security Best Practices](/docs/2025-11-25/tutorials/security/security_best_practices). A few key issues are called out below.
1004For comprehensive security guidance, including attack vectors, mitigation strategies, and implementation best practices, make sure to read through [Security Best Practices](/docs/2025-11-25/tutorials/security/security_best_practices.md). A few key issues are called out below.
10051005
10061006* **Do not implement token validation or authorization logic by yourself**. Use off-the-shelf, well-tested, and secure libraries for things like token validation or authorization decisions. Doing everything from scratch means that you're more likely to implement things incorrectly unless you are a security expert.
10071007* **Use short-lived access tokens**. Depending on the authorization server used, this setting might be customizable. We recommend to not use long-lived tokens - if a malicious actor steals them, they will be able to maintain their access for longer periods.
from line 1030
10301030
10311031For additional details, refer to:
10321032
1033* [Authorization Specification](/specification/2025-11-25/basic/authorization)
1034* [Security Best Practices](/docs/2025-11-25/tutorials/security/security_best_practices)
1035* [Available MCP SDKs](/docs/2025-11-25/sdk)
1033* [Authorization Specification](/specification/2025-11-25/basic/authorization.md)
1034* [Security Best Practices](/docs/2025-11-25/tutorials/security/security_best_practices.md)
1035* [Available MCP SDKs](/docs/2025-11-25/sdk.md)
10361036
10371037Understanding these standards will help you implement authorization correctly and troubleshoot issues when they arise.
10381038
docs/2025-11-25/tutorials/security/security_best_practices Changed · +4 / -4 lines
from line 8
88
99This document provides security considerations for the Model Context
1010Protocol (MCP), complementing the
11[MCP Authorization](/specification/2025-11-25/basic/authorization)
11[MCP Authorization](/specification/2025-11-25/basic/authorization.md)
1212specification. This document identifies security risks, attack vectors,
1313and best practices specific to MCP implementations.
1414
from line 148
148148 consent screen
1491496. The MCP authorization code is redirected to the attacker's server
150150 (specified in the malicious `redirect_uri` parameter during
151 [dynamic client registration](/specification/2025-11-25/basic/authorization#dynamic-client-registration))
151 [dynamic client registration](/specification/2025-11-25/basic/authorization.md#dynamic-client-registration))
1521527. The attacker exchanges the stolen authorization code for access
153153 tokens for the MCP server without the user's explicit approval
1541548. The attacker now has access to the third-party API as the compromised
from line 284
284284#### Risks
285285
286286Token passthrough is explicitly forbidden in the
287[authorization specification](/specification/2025-11-25/basic/authorization)
287[authorization specification](/specification/2025-11-25/basic/authorization.md)
288288as it introduces a number of security risks, that include:
289289
290290* **Security Control Circumvention**
from line 538
5385382. The attacker obtains an existing session ID and sends a malicious
539539 event to **Server B** with said session ID.
540540 * When a server supports
541 [redelivery/resumable streams](/specification/2025-11-25/basic/transports#resumability-and-redelivery),
541 [redelivery/resumable streams](/specification/2025-11-25/basic/transports.md#resumability-and-redelivery),
542542 deliberately terminating the request before receiving the response
543543 could lead to it being resumed by the original client via the GET
544544 request for server sent events.
docs/2026-07-28/develop/build-client Changed · +4 / -4 lines
from line 4
44
55In this tutorial, you'll learn how to build an LLM-powered chatbot client that connects to MCP servers.
66
7Before you begin, it helps to have gone through our [Build an MCP Server](/docs/2026-07-28/develop/build-server) tutorial so you can understand how clients and servers communicate.
7Before you begin, it helps to have gone through our [Build an MCP Server](/docs/2026-07-28/develop/build-server.md) tutorial so you can understand how clients and servers communicate.
88
99**Python**
1010
from line 371
371371 * Be cautious with tool permissions
372372
3733734. **Tool Names**
374 * Tool names can be validated according to the format specified [here](/specification/2026-07-28/server/tools#tool-names)
374 * Tool names can be validated according to the format specified [here](/specification/2026-07-28/server/tools.md#tool-names)
375375 * If a tool name conforms to the specified format, it should not fail validation by an MCP client
376376
377377## Troubleshooting
from line 1981
19811981 * Be cautious with tool permissions
19821982
198319834. **Tool Names**
1984 * Tool names can be validated according to the format specified [here](/specification/2026-07-28/server/tools#tool-names)
1984 * Tool names can be validated according to the format specified [here](/specification/2026-07-28/server/tools.md#tool-names)
19851985 * If a tool name conforms to the specified format, it should not fail validation by an MCP client
19861986
19871987## Troubleshooting
from line 2497
24972497
24982498## Next steps
24992499
2500> **[Example servers](/examples)**
2500> **[Example servers](/examples.md)**
25012501>
25022502> Check out our gallery of official MCP servers and implementations
25032503
docs/2026-07-28/develop/build-server Changed · +11 / -11 lines
from line 12
1212
1313> [!NOTE]
1414>
15> Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have a guide on [building your own client](/docs/2026-07-28/develop/build-client).
15> Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have a guide on [building your own client](/docs/2026-07-28/develop/build-client.md).
1616
1717### Core MCP Concepts
1818
1919MCP servers can provide three main types of capabilities:
2020
211. **[Resources](/docs/2026-07-28/learn/server-concepts#resources)**: File-like data that can be read by clients (like API responses or file contents)
222. **[Tools](/docs/2026-07-28/learn/server-concepts#tools)**: Functions that can be called by the LLM (with user approval)
233. **[Prompts](/docs/2026-07-28/learn/server-concepts#prompts)**: Pre-written templates that help users accomplish specific tasks
211. **[Resources](/docs/2026-07-28/learn/server-concepts.md#resources)**: File-like data that can be read by clients (like API responses or file contents)
222. **[Tools](/docs/2026-07-28/learn/server-concepts.md#tools)**: Functions that can be called by the LLM (with user approval)
233. **[Prompts](/docs/2026-07-28/learn/server-concepts.md#prompts)**: Pre-written templates that help users accomplish specific tasks
2424
2525This tutorial will primarily focus on tools.
2626
from line 707
707707
708708Make sure to run `npm run build` to build your server! This is a very important step in getting your server to connect.
709709
710To check that the server answers 2026-07-28 clients, list its tools with the [Inspector CLI](/docs/2026-07-28/tools/inspector/cli) in the `modern` [protocol era](/docs/2026-07-28/tools/inspector/protocol-eras):
710To check that the server answers 2026-07-28 clients, list its tools with the [Inspector CLI](/docs/2026-07-28/tools/inspector/cli.md) in the `modern` [protocol era](/docs/2026-07-28/tools/inspector/protocol-eras.md):
711711
712712```bash theme={null}
713713npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/list
from line 2895
28952895>
28962896> **None of this is working. What do I do?**
28972897>
2898> Please refer to our [debugging guide](/docs/2026-07-28/tools/debugging) for better debugging tools and more detailed guidance.
2898> Please refer to our [debugging guide](/docs/2026-07-28/tools/debugging.md) for better debugging tools and more detailed guidance.
28992899
29002900> **Weather API Issues**
29012901>
from line 2919
29192919
29202920> [!NOTE]
29212921>
2922> For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/2026-07-28/tools/debugging)
2922> For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/2026-07-28/tools/debugging.md)
29232923
29242924## Next steps
29252925
2926> **[Building a client](/docs/2026-07-28/develop/build-client)**
2926> **[Building a client](/docs/2026-07-28/develop/build-client.md)**
29272927>
29282928> Learn how to build your own MCP client that can connect to your server
29292929
2930> **[Example servers](/examples)**
2930> **[Example servers](/examples.md)**
29312931>
29322932> Check out our gallery of official MCP servers and implementations
29332933
2934> **[Debugging Guide](/docs/2026-07-28/tools/debugging)**
2934> **[Debugging Guide](/docs/2026-07-28/tools/debugging.md)**
29352935>
29362936> Learn how to effectively debug MCP servers and integrations
29372937
2938> **[Build with Agent Skills](/docs/2026-07-28/develop/build-with-agent-skills)**
2938> **[Build with Agent Skills](/docs/2026-07-28/develop/build-with-agent-skills.md)**
29392939>
29402940> Use agent skills to guide AI coding assistants through server design
29412941
docs/2026-07-28/develop/build-with-agent-skills Changed · +8 / -8 lines
from line 47
4747* **Who will use it** — just you, your team, or anyone who installs it
4848* **Action surface size** — a handful of operations versus wrapping a large API
4949* **User interaction needs** — plain text results, structured input via
50 [elicitation](/specification/2026-07-28/client/elicitation), or rich UI widgets
50 [elicitation](/specification/2026-07-28/client/elicitation.md), or rich UI widgets
5151* **Upstream auth** — API keys, OAuth 2.0, or none
5252
5353If your opening message already covers these, the agent skips ahead to the
from line 58
5858Based on discovery, the skill recommends one of four paths and scaffolds
5959accordingly:
6060
61**Remote [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http)**
61**Remote [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http.md)**
6262is the default for anything wrapping a cloud API. Zero install friction, one
6363deployment serves all users, and OAuth flows work properly because the server
6464can handle redirects and token storage. The reference skill includes scaffolds
6565for Cloudflare Workers and portable Express/FastMCP setups.
6666
67**[MCP apps](/extensions/apps/overview)** extend a server with interactive
67**[MCP apps](/extensions/apps/overview.md)** extend a server with interactive
6868widgets rendered in chat, such as searchable pickers, charts, and live
6969dashboards. The skill hands off to `build-mcp-app` when
70[elicitation's](/specification/2026-07-28/client/elicitation) flat-form constraints
70[elicitation's](/specification/2026-07-28/client/elicitation.md) flat-form constraints
7171don't fit.
7272
7373**[MCP Bundles (MCPB)](https://github.com/modelcontextprotocol/mcpb)** package a
from line 76
7676must touch the user's machine: reading local files, driving desktop apps, or
7777talking to localhost services. The skill hands off to `build-mcpb`.
7878
79**Local [stdio](/specification/2026-07-28/basic/transports/stdio)** remains available
79**Local [stdio](/specification/2026-07-28/basic/transports/stdio.md)** remains available
8080for prototyping, with a noted upgrade path to MCPB when you're ready to
8181distribute.
8282
from line 85
8585Once your agent scaffolds the server, iterate on tool descriptions and error
8686handling, then test and ship:
8787
88> **[MCP Inspector](/docs/2026-07-28/tools/inspector)**
88> **[MCP Inspector](/docs/2026-07-28/tools/inspector.md)**
8989>
9090> Test your server's tools, resources, and prompts interactively
9191
92> **[Connect to a client](/docs/2026-07-28/develop/connect-local-servers)**
92> **[Connect to a client](/docs/2026-07-28/develop/connect-local-servers.md)**
9393>
9494> Wire your server into an MCP client via local or remote configuration
9595
96> **[Publish to the Registry](/registry/quickstart)**
96> **[Publish to the Registry](/registry/quickstart.md)**
9797>
9898> Make your server discoverable in the MCP Registry
9999
docs/2026-07-28/develop/clients/client-best-practices Changed · +3 / -3 lines
from line 123
123123 Host-->>Model: Server disconnected, context freed
124124```
125125
126This works especially well for general-purpose agents, where the user's intent isn't known upfront. The agent starts with a minimal set of always-on servers and connects others as needed. Combined with [agent skills](/docs/2026-07-28/develop/build-with-agent-skills), a skill file can declare which MCP servers it needs, and the host connects them only when that skill is invoked.
126This works especially well for general-purpose agents, where the user's intent isn't known upfront. The agent starts with a minimal set of always-on servers and connects others as needed. Combined with [agent skills](/docs/2026-07-28/develop/build-with-agent-skills.md), a skill file can declare which MCP servers it needs, and the host connects them only when that skill is invoked.
127127
128128### Implementation Guidelines
129129
from line 140
140140
141141Each list result (such as `tools/list`), as well as each `server/discover` and
142142`resources/read` result, carries `ttlMs` and `cacheScope` hints. Follow them as defined in the
143specification's [caching utility](/specification/2026-07-28/server/utilities/caching). In particular,
143specification's [caching utility](/specification/2026-07-28/server/utilities/caching.md). In particular,
144144treat a cached list as stale once a `list_changed` notification arrives, even before its TTL
145145expires.
146146
from line 280
280280
281281Programmatic tool calling introduces a code execution surface that requires careful sandboxing:
282282
283* **Per-call authorization**: The broker is still the MCP host for spec purposes. Apply the same human-in-the-loop confirmation policy to sandbox-originated calls that you apply to direct calls (see [Tools: Security](/specification/2026-07-28/server/tools#security-considerations)). Approving the script does not grant blanket approval for every tool call it makes at runtime; hosts may grant categorical approval (for example, "allow `ticketing_createIssue` for this script run") rather than prompting per iteration, but the broker must still evaluate each call against that grant.
283* **Per-call authorization**: The broker is still the MCP host for spec purposes. Apply the same human-in-the-loop confirmation policy to sandbox-originated calls that you apply to direct calls (see [Tools: Security](/specification/2026-07-28/server/tools.md#security-considerations)). Approving the script does not grant blanket approval for every tool call it makes at runtime; hosts may grant categorical approval (for example, "allow `ticketing_createIssue` for this script run") rather than prompting per iteration, but the broker must still evaluate each call against that grant.
284284* **Cross-server data flow**: Tool results from one server are untrusted input to another. The broker should apply the same input-review policy to brokered calls as to direct ones; output truncation alone does not prevent exfiltration.
285285* **Network isolation**: The sandbox should have no direct network access. All external communication flows through the host broker, which enforces authorization and access control.
286286* **No credential exposure**: API keys and tokens are held by the host. The generated code calls typed functions; the host adds authentication when forwarding to servers.
docs/2026-07-28/develop/connect-local-servers Changed · +4 / -4 lines
from line 204
204204
205205> **None of this is working. What do I do?**
206206>
207> Please refer to our [debugging guide](/docs/2026-07-28/tools/debugging) for better debugging tools and more detailed guidance.
207> Please refer to our [debugging guide](/docs/2026-07-28/tools/debugging.md) for better debugging tools and more detailed guidance.
208208
209209> **ENOENT error and `$\{APPDATA\}` in paths on Windows**
210210>
from line 244
244244> Browse our collection of official and community-created MCP servers for
245245> additional capabilities
246246
247> **[Build your own server](/docs/2026-07-28/develop/build-server)**
247> **[Build your own server](/docs/2026-07-28/develop/build-server.md)**
248248>
249249> Create custom MCP servers tailored to your specific workflows and
250250> integrations
251251
252> **[Connect to remote servers](/docs/2026-07-28/develop/connect-remote-servers)**
252> **[Connect to remote servers](/docs/2026-07-28/develop/connect-remote-servers.md)**
253253>
254254> Learn how to connect Claude to remote MCP servers for cloud-based tools and
255255> services
256256
257> **[Understand the protocol](/docs/2026-07-28/learn/architecture)**
257> **[Understand the protocol](/docs/2026-07-28/learn/architecture.md)**
258258>
259259> Dive deeper into how MCP works and its architecture
260260
docs/2026-07-28/develop/connect-remote-servers Changed · +4 / -4 lines
from line 19
1919With Custom Connectors, you can:
2020
2121* [Connect Claude to existing remote MCP servers](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) provided by third-party developers
22* [Build your own remote MCP servers to connect with any tool](/docs/2026-07-28/develop/build-server)
22* [Build your own remote MCP servers to connect with any tool](/docs/2026-07-28/develop/build-server.md)
2323
2424## Connecting to a Remote MCP Server
2525
from line 88
8888
8989Now that you've connected Claude to a remote MCP server, you can explore its capabilities in your conversations. Try using the connected tools to automate tasks, access external data, or integrate with your existing workflows.
9090
91> **[Build your own remote server](/docs/2026-07-28/develop/build-server)**
91> **[Build your own remote server](/docs/2026-07-28/develop/build-server.md)**
9292>
9393> Create custom remote MCP servers to integrate with proprietary tools and
9494> services
from line 97
9797>
9898> Browse our collection of official and community-created MCP servers
9999
100> **[Connect local servers](/docs/2026-07-28/develop/connect-local-servers)**
100> **[Connect local servers](/docs/2026-07-28/develop/connect-local-servers.md)**
101101>
102102> Learn how to connect Claude Desktop to local MCP servers for direct system
103103> access
104104
105> **[Understand the architecture](/docs/2026-07-28/learn/architecture)**
105> **[Understand the architecture](/docs/2026-07-28/learn/architecture.md)**
106106>
107107> Dive deeper into how MCP works and its architecture
108108