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
26-50 of 295, page 2 of 12This capture is too large to show at once. Changes 26-50 of 295 are below, significant first; the rest are on the following screens.
docs/2024-11-05/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/2024-11-05/sdk).
7For specific implementation details, please refer to the documentation for your [language-specific SDK](/docs/2024-11-05/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/2024-11-05/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/2024-11-05/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 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/2024-11-05/basic/lifecycle), and the [example](#example) showcases the initialization sequence.
107MCP is a stateful protocol 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/2024-11-05/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/2024-11-05/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 128
128128* **Sampling**: Allows servers to request language model completions from the client's AI application. This is useful when server authors want access to a language model, but want to stay model-independent and not include a language model SDK in their MCP server. They can use the `sampling/createMessage` method to request a language model completion from the client's AI application.
129129* **Logging**: Enables servers to send log messages to clients for debugging and monitoring purposes.
130130
131For more details about client primitives see [client concepts](./client-concepts).
131For more details about client primitives see [client concepts](/docs/2024-11-05/learn/client-concepts.md).
132132
133133Besides server and client primitives, the protocol offers cross-cutting utility primitives that augment how requests are executed:
134134
docs/2024-11-05/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/2024-11-05/basic/lifecycle#initialization). Clients and
39[initialization](/specification/2024-11-05/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/2024-11-05/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/2024-11-05/develop/build-server)**
39> **[Build a Server](/docs/2024-11-05/develop/build-server.md)**
4040>
4141> Learn how to create your first MCP server
4242
43> **[Build a Client](/docs/2024-11-05/develop/build-client)**
43> **[Build a Client](/docs/2024-11-05/develop/build-client.md)**
4444>
4545> Create applications that connect to MCP servers
4646
docs/2024-11-05/tools/debugging Changed · +19 / -19 lines
from line 10
1010
1111MCP provides several tools for debugging at different levels:
1212
131. **[MCP Inspector](/docs/2024-11-05/tools/inspector)**: interactive, transport-agnostic
131. **[MCP Inspector](/docs/2024-11-05/tools/inspector.md)**: interactive, transport-agnostic
1414 testing UI. Connect to stdio or HTTP with SSE servers, invoke
15 [tools](/specification/2024-11-05/server/tools),
16 [prompts](/specification/2024-11-05/server/prompts), and
17 [resources](/specification/2024-11-05/server/resources), and watch the
15 [tools](/specification/2024-11-05/server/tools.md),
16 [prompts](/specification/2024-11-05/server/prompts.md), and
17 [resources](/specification/2024-11-05/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/2024-11-05/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/2024-11-05/basic/transports#stdio), all messages
31[stdio transport](/specification/2024-11-05/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[HTTP with SSE transport](/specification/2024-11-05/basic/transports#http-with-sse),
41[HTTP with SSE transport](/specification/2024-11-05/basic/transports.md#http-with-sse),
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 and SSE streams.
4545
46For all [transports](/specification/2024-11-05/basic/transports), you can also
46For all [transports](/specification/2024-11-05/basic/transports.md), you can also
4747provide logging to the client by sending a log message notification:
4848
4949```python Python theme={null}
from line 64
6464```
6565
6666MCP defines eight
67[RFC 5424 severity levels](/specification/2024-11-05/server/utilities/logging#log-levels)
67[RFC 5424 severity levels](/specification/2024-11-05/server/utilities/logging.md#log-levels)
6868(`debug` through `emergency`). Clients can adjust the minimum level at runtime
6969via the
7070[`logging/setLevel`](/specification/2024-11-05/server/utilities/logging#setting-log-level)
from line 162
162162
1631631. Check client logs
1641642. Verify server process is running
1653. Test standalone with [Inspector](/docs/2024-11-05/tools/inspector)
1653. Test standalone with [Inspector](/docs/2024-11-05/tools/inspector.md)
1661664. Verify
167 [protocol compatibility](/specification/2024-11-05/basic/lifecycle#version-negotiation)
167 [protocol compatibility](/specification/2024-11-05/basic/lifecycle.md#version-negotiation)
1681685. Check
169 [capability negotiation](/specification/2024-11-05/basic/lifecycle#capability-negotiation):
169 [capability negotiation](/specification/2024-11-05/basic/lifecycle.md#capability-negotiation):
170170 error [`-32602`](/specification/2024-11-05/basic/lifecycle#error-handling) is
171171 the standard JSON-RPC "Invalid params" code and is returned in many
172172 contexts. One common cause is a server sending
173 [sampling](/specification/2024-11-05/client/sampling) requests to a
173 [sampling](/specification/2024-11-05/client/sampling.md) requests to a
174174 client that hasn't declared that capability. Inspect the
175175 [`initialize` exchange](/specification/2024-11-05/basic/lifecycle#initialization)
176176 to verify both sides declared what you expect
from line 244
244244### Development cycle
245245
2462461. Initial Development
247 * Use [Inspector](/docs/2024-11-05/tools/inspector) for basic testing
247 * Use [Inspector](/docs/2024-11-05/tools/inspector.md) for basic testing
248248 * Implement core functionality
249249 * Add logging points
250250
from line 260
260260* **Configuration changes**: Restart the MCP client
261261* **Server code changes**: Restart the client (for Claude Desktop, fully quit
262262 and reopen; closing the window is not enough)
263* **Quick iteration**: Use [Inspector](/docs/2024-11-05/tools/inspector) during
263* **Quick iteration**: Use [Inspector](/docs/2024-11-05/tools/inspector.md) during
264264 development
265265
266266## Best practices
from line 300
300300 * Monitor access patterns
301301
302302For a full treatment of MCP attack vectors and mitigations, see
303[Security Best Practices](/docs/2024-11-05/tutorials/security/security_best_practices).
303[Security Best Practices](/docs/2024-11-05/tutorials/security/security_best_practices.md).
304304
305305## Getting help
306306
from line 308
308308
3093091. **First Steps**
310310 * Check server logs
311 * Test with [Inspector](/docs/2024-11-05/tools/inspector)
311 * Test with [Inspector](/docs/2024-11-05/tools/inspector.md)
312312 * Review configuration
313313 * Verify environment
314314
from line 324
324324
325325## Next steps
326326
327> **[MCP Inspector](/docs/2024-11-05/tools/inspector)**
327> **[MCP Inspector](/docs/2024-11-05/tools/inspector.md)**
328328>
329329> Learn to use the MCP Inspector
330330
331> **[Build an MCP server](/docs/2024-11-05/develop/build-server)**
331> **[Build an MCP server](/docs/2024-11-05/develop/build-server.md)**
332332>
333333> Walk through building a server from scratch
334334
335> **[Connect local servers](/docs/2024-11-05/develop/connect-local-servers)**
335> **[Connect local servers](/docs/2024-11-05/develop/connect-local-servers.md)**
336336>
337337> Full claude\_desktop\_config.json reference and troubleshooting
338338
docs/2024-11-05/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/2024-11-05/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/2024-11-05/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/2024-11-05/basic/transports) for connecting to the server
75* Allows selecting the [transport](/specification/2024-11-05/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/2024-11-05/tools/debugging)**
132> **[Debugging Guide](/docs/2024-11-05/tools/debugging.md)**
131133>
132134> Learn about broader debugging strategies
133135
docs/2024-11-05/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-03-26/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-03-26/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/2024-11-05/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/2024-11-05/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/2024-11-05/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/2024-11-05/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/2024-11-05/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/2024-11-05/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-03-26/basic/authorization)
1034* [Security Best Practices](/docs/2024-11-05/tutorials/security/security_best_practices)
1035* [Available MCP SDKs](/docs/2024-11-05/sdk)
1033* [Authorization Specification](/specification/2025-03-26/basic/authorization.md)
1034* [Security Best Practices](/docs/2024-11-05/tutorials/security/security_best_practices.md)
1035* [Available MCP SDKs](/docs/2024-11-05/sdk.md)
10361036
10371037Understanding these standards will help you implement authorization correctly and troubleshoot issues when they arise.
10381038
docs/2024-11-05/tutorials/security/security_best_practices Changed · +3 / -3 lines
from line 8
88
99This document provides security considerations for the Model Context
1010Protocol (MCP), complementing the
11[MCP Authorization](/specification/2025-03-26/basic/authorization)
11[MCP Authorization](/specification/2025-03-26/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-03-26/basic/authorization#dynamic-client-registration))
151 [dynamic client registration](/specification/2025-03-26/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-03-26/basic/authorization)
287[authorization specification](/specification/2025-03-26/basic/authorization.md)
288288as it introduces a number of security risks, that include:
289289
290290* **Security Control Circumvention**
docs/2025-03-26/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-03-26/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-03-26/develop/build-client.md).
1616
1717### Core MCP Concepts
1818
1919MCP servers can provide three main types of capabilities:
2020
211. **[Resources](/docs/2025-03-26/learn/server-concepts#resources)**: File-like data that can be read by clients (like API responses or file contents)
222. **[Tools](/docs/2025-03-26/learn/server-concepts#tools)**: Functions that can be called by the LLM (with user approval)
233. **[Prompts](/docs/2025-03-26/learn/server-concepts#prompts)**: Pre-written templates that help users accomplish specific tasks
211. **[Resources](/docs/2025-03-26/learn/server-concepts.md#resources)**: File-like data that can be read by clients (like API responses or file contents)
222. **[Tools](/docs/2025-03-26/learn/server-concepts.md#tools)**: Functions that can be called by the LLM (with user approval)
233. **[Prompts](/docs/2025-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/tools/debugging) for better debugging tools and more detailed guidance.
2887> Please refer to our [debugging guide](/docs/2025-03-26/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-03-26/tools/debugging)
2911> For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/2025-03-26/tools/debugging.md)
29122912
29132913## Next steps
29142914
2915> **[Building a client](/docs/2025-03-26/develop/build-client)**
2915> **[Building a client](/docs/2025-03-26/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-03-26/tools/debugging)**
2923> **[Debugging Guide](/docs/2025-03-26/tools/debugging.md)**
29242924>
29252925> Learn how to effectively debug MCP servers and integrations
29262926
2927> **[Build with Agent Skills](/docs/2025-03-26/develop/build-with-agent-skills)**
2927> **[Build with Agent Skills](/docs/2025-03-26/develop/build-with-agent-skills.md)**
29282928>
29292929> Use agent skills to guide AI coding assistants through server design
29302930
docs/2025-03-26/develop/build-with-agent-skills Changed · +6 / -6 lines
from line 57
5757Based on discovery, the skill recommends one of four paths and scaffolds
5858accordingly:
5959
60**Remote [Streamable HTTP](/specification/2025-03-26/basic/transports#streamable-http)**
60**Remote [Streamable HTTP](/specification/2025-03-26/basic/transports.md#streamable-http)**
6161is the default for anything wrapping a cloud API. Zero install friction, one
6262deployment serves all users, and OAuth flows work properly because the server
6363can handle redirects and token storage. The reference skill includes scaffolds
6464for Cloudflare Workers and portable Express/FastMCP setups.
6565
66**[MCP apps](/extensions/apps/overview)** extend a server with interactive
66**[MCP apps](/extensions/apps/overview.md)** extend a server with interactive
6767widgets rendered in chat, such as searchable pickers, charts, and live
6868dashboards. The skill hands off to `build-mcp-app` when plain text output
6969doesn't fit.
from line 74
7474must touch the user's machine: reading local files, driving desktop apps, or
7575talking to localhost services. The skill hands off to `build-mcpb`.
7676
77**Local [stdio](/specification/2025-03-26/basic/transports#stdio)** remains available
77**Local [stdio](/specification/2025-03-26/basic/transports.md#stdio)** remains available
7878for prototyping, with a noted upgrade path to MCPB when you're ready to
7979distribute.
8080
from line 83
8383Once your agent scaffolds the server, iterate on tool descriptions and error
8484handling, then test and ship:
8585
86> **[MCP Inspector](/docs/2025-03-26/tools/inspector)**
86> **[MCP Inspector](/docs/2025-03-26/tools/inspector.md)**
8787>
8888> Test your server's tools, resources, and prompts interactively
8989
90> **[Connect to a client](/docs/2025-03-26/develop/connect-local-servers)**
90> **[Connect to a client](/docs/2025-03-26/develop/connect-local-servers.md)**
9191>
9292> Wire your server into an MCP client via local or remote configuration
9393
94> **[Publish to the Registry](/registry/quickstart)**
94> **[Publish to the Registry](/registry/quickstart.md)**
9595>
9696> Make your server discoverable in the MCP Registry
9797
docs/2025-03-26/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-03-26/tools/debugging) for better debugging tools and more detailed guidance.
207> Please refer to our [debugging guide](/docs/2025-03-26/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-03-26/develop/build-server)**
247> **[Build your own server](/docs/2025-03-26/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-03-26/develop/connect-remote-servers)**
252> **[Connect to remote servers](/docs/2025-03-26/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-03-26/learn/architecture)**
257> **[Understand the protocol](/docs/2025-03-26/learn/architecture.md)**
258258>
259259> Dive deeper into how MCP works and its architecture
260260
docs/2025-03-26/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-03-26/develop/build-server)
22* [Build your own remote MCP servers to connect with any tool](/docs/2025-03-26/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-03-26/develop/build-server)**
84> **[Build your own remote server](/docs/2025-03-26/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-03-26/develop/connect-local-servers)**
93> **[Connect local servers](/docs/2025-03-26/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-03-26/learn/architecture)**
98> **[Understand the architecture](/docs/2025-03-26/learn/architecture.md)**
9999>
100100> Dive deeper into how MCP works and its architecture
101101
docs/2025-03-26/getting-started/intro Changed · +6 / -6 lines
from line 29
2929
3030## Start Building
3131
32> **[Build servers](/docs/2025-03-26/develop/build-server)**
32> **[Build servers](/docs/2025-03-26/develop/build-server.md)**
3333>
3434> Create MCP servers to expose your data and tools
3535
36> **[Build clients](/docs/2025-03-26/develop/build-client)**
36> **[Build clients](/docs/2025-03-26/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-03-26/learn/architecture)**
46> **[Architecture](/docs/2025-03-26/learn/architecture.md)**
4747>
4848> Learn the core concepts and architecture of MCP
4949
50> **[Security](/docs/2025-03-26/tutorials/security/security_best_practices)**
50> **[Security](/docs/2025-03-26/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-03-26/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-03-26/sdk).
7For specific implementation details, please refer to the documentation for your [language-specific SDK](/docs/2025-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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 128
128128* **Sampling**: Allows servers to request language model completions from the client's AI application. This is useful when server authors want access to a language model, but want to stay model-independent and not include a language model SDK in their MCP server. They can use the `sampling/createMessage` method to request a language model completion from the client's AI application.
129129* **Logging**: Enables servers to send log messages to clients for debugging and monitoring purposes.
130130
131For more details about client primitives see [client concepts](./client-concepts).
131For more details about client primitives see [client concepts](/docs/2025-03-26/learn/client-concepts.md).
132132
133133Besides server and client primitives, the protocol offers cross-cutting utility primitives that augment how requests are executed:
134134
docs/2025-03-26/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-03-26/basic/lifecycle#initialization). Clients and
39[initialization](/specification/2025-03-26/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-03-26/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-03-26/develop/build-server)**
39> **[Build a Server](/docs/2025-03-26/develop/build-server.md)**
4040>
4141> Learn how to create your first MCP server
4242
43> **[Build a Client](/docs/2025-03-26/develop/build-client)**
43> **[Build a Client](/docs/2025-03-26/develop/build-client.md)**
4444>
4545> Create applications that connect to MCP servers
4646
docs/2025-03-26/tools/debugging Changed · +19 / -19 lines
from line 10
1010
1111MCP provides several tools for debugging at different levels:
1212
131. **[MCP Inspector](/docs/2025-03-26/tools/inspector)**: interactive, transport-agnostic
131. **[MCP Inspector](/docs/2025-03-26/tools/inspector.md)**: interactive, transport-agnostic
1414 testing UI. Connect to stdio or Streamable HTTP servers, invoke
15 [tools](/specification/2025-03-26/server/tools),
16 [prompts](/specification/2025-03-26/server/prompts), and
17 [resources](/specification/2025-03-26/server/resources), and watch the
15 [tools](/specification/2025-03-26/server/tools.md),
16 [prompts](/specification/2025-03-26/server/prompts.md), and
17 [resources](/specification/2025-03-26/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-03-26/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-03-26/basic/transports#stdio), all messages
31[stdio transport](/specification/2025-03-26/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-03-26/basic/transports#streamable-http),
41[Streamable HTTP transport](/specification/2025-03-26/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-03-26/basic/transports#session-management),
4646and SSE streams.
4747
48For all [transports](/specification/2025-03-26/basic/transports), you can also
48For all [transports](/specification/2025-03-26/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-03-26/server/utilities/logging#log-levels)
69[RFC 5424 severity levels](/specification/2025-03-26/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-03-26/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-03-26/tools/inspector)
1673. Test standalone with [Inspector](/docs/2025-03-26/tools/inspector.md)
1681684. Verify
169 [protocol compatibility](/specification/2025-03-26/basic/lifecycle#version-negotiation)
169 [protocol compatibility](/specification/2025-03-26/basic/lifecycle.md#version-negotiation)
1701705. Check
171 [capability negotiation](/specification/2025-03-26/basic/lifecycle#capability-negotiation):
171 [capability negotiation](/specification/2025-03-26/basic/lifecycle.md#capability-negotiation):
172172 error [`-32602`](/specification/2025-03-26/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-03-26/client/sampling) requests to a
175 [sampling](/specification/2025-03-26/client/sampling.md) requests to a
176176 client that hasn't declared that capability. Inspect the
177177 [`initialize` exchange](/specification/2025-03-26/basic/lifecycle#initialization)
178178 to verify both sides declared what you expect
from line 246
246246### Development cycle
247247
2482481. Initial Development
249 * Use [Inspector](/docs/2025-03-26/tools/inspector) for basic testing
249 * Use [Inspector](/docs/2025-03-26/tools/inspector.md) for basic testing
250250 * Implement core functionality
251251 * Add logging points
252252
from line 262
262262* **Configuration changes**: Restart the MCP client
263263* **Server code changes**: Restart the client (for Claude Desktop, fully quit
264264 and reopen; closing the window is not enough)
265* **Quick iteration**: Use [Inspector](/docs/2025-03-26/tools/inspector) during
265* **Quick iteration**: Use [Inspector](/docs/2025-03-26/tools/inspector.md) during
266266 development
267267
268268## Best practices
from line 302
302302 * Monitor access patterns
303303
304304For a full treatment of MCP attack vectors and mitigations, see
305[Security Best Practices](/docs/2025-03-26/tutorials/security/security_best_practices).
305[Security Best Practices](/docs/2025-03-26/tutorials/security/security_best_practices.md).
306306
307307## Getting help
308308
from line 310
310310
3113111. **First Steps**
312312 * Check server logs
313 * Test with [Inspector](/docs/2025-03-26/tools/inspector)
313 * Test with [Inspector](/docs/2025-03-26/tools/inspector.md)
314314 * Review configuration
315315 * Verify environment
316316
from line 326
326326
327327## Next steps
328328
329> **[MCP Inspector](/docs/2025-03-26/tools/inspector)**
329> **[MCP Inspector](/docs/2025-03-26/tools/inspector.md)**
330330>
331331> Learn to use the MCP Inspector
332332
333> **[Build an MCP server](/docs/2025-03-26/develop/build-server)**
333> **[Build an MCP server](/docs/2025-03-26/develop/build-server.md)**
334334>
335335> Walk through building a server from scratch
336336
337> **[Connect local servers](/docs/2025-03-26/develop/connect-local-servers)**
337> **[Connect local servers](/docs/2025-03-26/develop/connect-local-servers.md)**
338338>
339339> Full claude\_desktop\_config.json reference and troubleshooting
340340
docs/2025-03-26/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-03-26/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-03-26/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-03-26/basic/transports) for connecting to the server
75* Allows selecting the [transport](/specification/2025-03-26/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-03-26/tools/debugging)**
132> **[Debugging Guide](/docs/2025-03-26/tools/debugging.md)**
131133>
132134> Learn about broader debugging strategies
133135
docs/2025-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/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-03-26/basic/authorization)
1034* [Security Best Practices](/docs/2025-03-26/tutorials/security/security_best_practices)
1035* [Available MCP SDKs](/docs/2025-03-26/sdk)
1033* [Authorization Specification](/specification/2025-03-26/basic/authorization.md)
1034* [Security Best Practices](/docs/2025-03-26/tutorials/security/security_best_practices.md)
1035* [Available MCP SDKs](/docs/2025-03-26/sdk.md)
10361036
10371037Understanding these standards will help you implement authorization correctly and troubleshoot issues when they arise.
10381038
docs/2025-03-26/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-03-26/basic/authorization)
11[MCP Authorization](/specification/2025-03-26/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-03-26/basic/authorization#dynamic-client-registration))
151 [dynamic client registration](/specification/2025-03-26/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-03-26/basic/authorization)
287[authorization specification](/specification/2025-03-26/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-03-26/basic/transports#resumability-and-redelivery),
541 [redelivery/resumable streams](/specification/2025-03-26/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-06-18/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-06-18/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-06-18/develop/build-client.md).
1616
1717### Core MCP Concepts
1818
1919MCP servers can provide three main types of capabilities:
2020
211. **[Resources](/docs/2025-06-18/learn/server-concepts#resources)**: File-like data that can be read by clients (like API responses or file contents)
222. **[Tools](/docs/2025-06-18/learn/server-concepts#tools)**: Functions that can be called by the LLM (with user approval)
233. **[Prompts](/docs/2025-06-18/learn/server-concepts#prompts)**: Pre-written templates that help users accomplish specific tasks
211. **[Resources](/docs/2025-06-18/learn/server-concepts.md#resources)**: File-like data that can be read by clients (like API responses or file contents)
222. **[Tools](/docs/2025-06-18/learn/server-concepts.md#tools)**: Functions that can be called by the LLM (with user approval)
233. **[Prompts](/docs/2025-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/tools/debugging) for better debugging tools and more detailed guidance.
2887> Please refer to our [debugging guide](/docs/2025-06-18/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-06-18/tools/debugging)
2911> For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/2025-06-18/tools/debugging.md)
29122912
29132913## Next steps
29142914
2915> **[Building a client](/docs/2025-06-18/develop/build-client)**
2915> **[Building a client](/docs/2025-06-18/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-06-18/tools/debugging)**
2923> **[Debugging Guide](/docs/2025-06-18/tools/debugging.md)**
29242924>
29252925> Learn how to effectively debug MCP servers and integrations
29262926
2927> **[Build with Agent Skills](/docs/2025-06-18/develop/build-with-agent-skills)**
2927> **[Build with Agent Skills](/docs/2025-06-18/develop/build-with-agent-skills.md)**
29282928>
29292929> Use agent skills to guide AI coding assistants through server design
29302930
docs/2025-06-18/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-06-18/client/elicitation), or rich UI widgets
50 [elicitation](/specification/2025-06-18/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-06-18/basic/transports#streamable-http)**
61**Remote [Streamable HTTP](/specification/2025-06-18/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-06-18/client/elicitation) flat-form constraints
70[elicitation's](/specification/2025-06-18/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-06-18/basic/transports#stdio)** remains available
79**Local [stdio](/specification/2025-06-18/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-06-18/tools/inspector)**
88> **[MCP Inspector](/docs/2025-06-18/tools/inspector.md)**
8989>
9090> Test your server's tools, resources, and prompts interactively
9191
92> **[Connect to a client](/docs/2025-06-18/develop/connect-local-servers)**
92> **[Connect to a client](/docs/2025-06-18/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-06-18/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-06-18/tools/debugging) for better debugging tools and more detailed guidance.
207> Please refer to our [debugging guide](/docs/2025-06-18/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-06-18/develop/build-server)**
247> **[Build your own server](/docs/2025-06-18/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-06-18/develop/connect-remote-servers)**
252> **[Connect to remote servers](/docs/2025-06-18/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-06-18/learn/architecture)**
257> **[Understand the protocol](/docs/2025-06-18/learn/architecture.md)**
258258>
259259> Dive deeper into how MCP works and its architecture
260260
docs/2025-06-18/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-06-18/develop/build-server)
22* [Build your own remote MCP servers to connect with any tool](/docs/2025-06-18/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-06-18/develop/build-server)**
84> **[Build your own remote server](/docs/2025-06-18/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-06-18/develop/connect-local-servers)**
93> **[Connect local servers](/docs/2025-06-18/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-06-18/learn/architecture)**
98> **[Understand the architecture](/docs/2025-06-18/learn/architecture.md)**
9999>
100100> Dive deeper into how MCP works and its architecture
101101
docs/2025-06-18/getting-started/intro Changed · +6 / -6 lines
from line 29
2929
3030## Start Building
3131
32> **[Build servers](/docs/2025-06-18/develop/build-server)**
32> **[Build servers](/docs/2025-06-18/develop/build-server.md)**
3333>
3434> Create MCP servers to expose your data and tools
3535
36> **[Build clients](/docs/2025-06-18/develop/build-client)**
36> **[Build clients](/docs/2025-06-18/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-06-18/learn/architecture)**
46> **[Architecture](/docs/2025-06-18/learn/architecture.md)**
4747>
4848> Learn the core concepts and architecture of MCP
4949
50> **[Security](/docs/2025-06-18/tutorials/security/security_best_practices)**
50> **[Security](/docs/2025-06-18/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-06-18/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-06-18/sdk).
7For specific implementation details, please refer to the documentation for your [language-specific SDK](/docs/2025-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/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-06-18/learn/client-concepts.md).
133133
134134Besides server and client primitives, the protocol offers cross-cutting utility primitives that augment how requests are executed:
135135