├── .gitattributes ├── .github └── workflows │ ├── main.yml │ └── markdown-format.yml ├── .gitignore ├── .npmrc ├── .nvmrc ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── SECURITY.md ├── docs ├── clients.mdx ├── development │ ├── contributing.mdx │ ├── roadmap.mdx │ └── updates.mdx ├── docs.json ├── docs │ ├── concepts │ │ ├── architecture.mdx │ │ ├── prompts.mdx │ │ ├── resources.mdx │ │ ├── roots.mdx │ │ ├── sampling.mdx │ │ ├── tools.mdx │ │ └── transports.mdx │ └── tools │ │ ├── debugging.mdx │ │ └── inspector.mdx ├── examples.mdx ├── faqs.mdx ├── favicon.svg ├── images │ ├── available-mcp-tools.png │ ├── claude-desktop-mcp-plug-icon.svg │ ├── claude-desktop-mcp-slider.svg │ ├── client-claude-cli-python.png │ ├── current-weather.png │ ├── hero-dark.svg │ ├── hero-light.svg │ ├── java │ │ ├── class-diagrams.puml │ │ ├── java-mcp-client-architecture.jpg │ │ ├── java-mcp-server-architecture.jpg │ │ ├── java-mcp-uml-classdiagram.svg │ │ └── mcp-stack.svg │ ├── mcp-inspector.png │ ├── mcp-simple-diagram.png │ ├── og-image.png │ ├── quickstart-approve.png │ ├── quickstart-developer.png │ ├── quickstart-dotnet-client.png │ ├── quickstart-filesystem.png │ ├── quickstart-menu.png │ ├── quickstart-screenshot.png │ ├── quickstart-slider.png │ ├── quickstart-tools.png │ ├── visual-indicator-mcp-tools.png │ └── weather-alerts.png ├── introduction.mdx ├── logo │ ├── dark.png │ ├── dark.svg │ ├── light.png │ └── light.svg ├── quickstart │ ├── client.mdx │ ├── server.mdx │ └── user.mdx ├── sdk │ └── java │ │ ├── mcp-client.mdx │ │ ├── mcp-overview.mdx │ │ └── mcp-server.mdx ├── snippets │ └── snippet-intro.mdx ├── specification │ ├── 2024-11-05 │ │ ├── architecture │ │ │ └── index.mdx │ │ ├── basic │ │ │ ├── index.mdx │ │ │ ├── lifecycle.mdx │ │ │ ├── messages.mdx │ │ │ ├── transports.mdx │ │ │ └── utilities │ │ │ │ ├── cancellation.mdx │ │ │ │ ├── ping.mdx │ │ │ │ └── progress.mdx │ │ ├── client │ │ │ ├── roots.mdx │ │ │ └── sampling.mdx │ │ ├── index.mdx │ │ └── server │ │ │ ├── index.mdx │ │ │ ├── prompts.mdx │ │ │ ├── resource-picker.png │ │ │ ├── resources.mdx │ │ │ ├── slash-command.png │ │ │ ├── tools.mdx │ │ │ └── utilities │ │ │ ├── completion.mdx │ │ │ ├── logging.mdx │ │ │ └── pagination.mdx │ ├── 2025-03-26 │ │ ├── architecture │ │ │ └── index.mdx │ │ ├── basic │ │ │ ├── authorization.mdx │ │ │ ├── index.mdx │ │ │ ├── lifecycle.mdx │ │ │ ├── transports.mdx │ │ │ └── utilities │ │ │ │ ├── cancellation.mdx │ │ │ │ ├── ping.mdx │ │ │ │ └── progress.mdx │ │ ├── changelog.mdx │ │ ├── client │ │ │ ├── roots.mdx │ │ │ └── sampling.mdx │ │ ├── index.mdx │ │ └── server │ │ │ ├── index.mdx │ │ │ ├── prompts.mdx │ │ │ ├── resource-picker.png │ │ │ ├── resources.mdx │ │ │ ├── slash-command.png │ │ │ ├── tools.mdx │ │ │ └── utilities │ │ │ ├── completion.mdx │ │ │ ├── logging.mdx │ │ │ └── pagination.mdx │ ├── contributing.mdx │ ├── draft │ │ ├── architecture │ │ │ └── index.mdx │ │ ├── basic │ │ │ ├── authorization.mdx │ │ │ ├── index.mdx │ │ │ ├── lifecycle.mdx │ │ │ ├── security_best_practices.mdx │ │ │ ├── transports.mdx │ │ │ └── utilities │ │ │ │ ├── cancellation.mdx │ │ │ │ ├── ping.mdx │ │ │ │ └── progress.mdx │ │ ├── changelog.mdx │ │ ├── client │ │ │ ├── elicitation.mdx │ │ │ ├── roots.mdx │ │ │ └── sampling.mdx │ │ ├── index.mdx │ │ └── server │ │ │ ├── index.mdx │ │ │ ├── prompts.mdx │ │ │ ├── resource-picker.png │ │ │ ├── resources.mdx │ │ │ ├── slash-command.png │ │ │ ├── tools.mdx │ │ │ └── utilities │ │ │ ├── completion.mdx │ │ │ ├── logging.mdx │ │ │ └── pagination.mdx │ └── versioning.mdx ├── style.css └── tutorials │ ├── building-a-client-node.mdx │ └── building-mcp-with-llms.mdx ├── package-lock.json ├── package.json ├── schema ├── 2024-11-05 │ ├── schema.json │ └── schema.ts ├── 2025-03-26 │ ├── schema.json │ └── schema.ts └── draft │ ├── schema.json │ └── schema.ts └── tsconfig.json /.gitattributes: -------------------------------------------------------------------------------- 1 | package-lock.json linguist-generated=true 2 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | on: 2 | push: 3 | branches: 4 | - main 5 | 6 | pull_request: 7 | 8 | jobs: 9 | validate: 10 | runs-on: ubuntu-latest 11 | 12 | steps: 13 | - uses: actions/checkout@v4 14 | - uses: actions/setup-node@v4 15 | with: 16 | node-version: 20 17 | cache: npm 18 | 19 | - run: npm ci 20 | 21 | - run: npm run validate:schema 22 | 23 | - run: npm run generate:json 24 | - name: Verify that `npm run generate:json` did not change outputs (if it did, please re-run it and re-commit!) 25 | run: git diff --exit-code 26 | -------------------------------------------------------------------------------- /.github/workflows/markdown-format.yml: -------------------------------------------------------------------------------- 1 | name: Markdown Format Check 2 | 3 | on: 4 | push: 5 | paths: 6 | - '**/*.md' 7 | pull_request: 8 | paths: 9 | - '**/*.md' 10 | 11 | jobs: 12 | format: 13 | runs-on: ubuntu-latest 14 | steps: 15 | - uses: actions/checkout@v4 16 | 17 | - name: Setup Node.js 18 | uses: actions/setup-node@v4 19 | with: 20 | node-version: '20' 21 | 22 | - name: Install dependencies 23 | run: npm ci 24 | 25 | - name: Check markdown formatting 26 | run: npm run format:check -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | .DS_Store 3 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | registry = "https://registry.npmjs.org/" 2 | -------------------------------------------------------------------------------- /.nvmrc: -------------------------------------------------------------------------------- 1 | v20.16.0 2 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We as members, contributors, and leaders pledge to make participation in our community a 6 | harassment-free experience for everyone, regardless of age, body size, visible or 7 | invisible disability, ethnicity, sex characteristics, gender identity and expression, 8 | level of experience, education, socio-economic status, nationality, personal appearance, 9 | race, religion, or sexual identity and orientation. 10 | 11 | We pledge to act and interact in ways that contribute to an open, welcoming, diverse, 12 | inclusive, and healthy community. 13 | 14 | ## Our Standards 15 | 16 | Examples of behavior that contributes to a positive environment for our community 17 | include: 18 | 19 | - Demonstrating empathy and kindness toward other people 20 | - Being respectful of differing opinions, viewpoints, and experiences 21 | - Giving and gracefully accepting constructive feedback 22 | - Accepting responsibility and apologizing to those affected by our mistakes, and 23 | learning from the experience 24 | - Focusing on what is best not just for us as individuals, but for the overall community 25 | 26 | Examples of unacceptable behavior include: 27 | 28 | - The use of sexualized language or imagery, and sexual attention or advances of any kind 29 | - Trolling, insulting or derogatory comments, and personal or political attacks 30 | - Public or private harassment 31 | - Publishing others' private information, such as a physical or email address, without 32 | their explicit permission 33 | - Other conduct which could reasonably be considered inappropriate in a professional 34 | setting 35 | 36 | ## Enforcement Responsibilities 37 | 38 | Community leaders are responsible for clarifying and enforcing our standards of 39 | acceptable behavior and will take appropriate and fair corrective action in response to 40 | any behavior that they deem inappropriate, threatening, offensive, or harmful. 41 | 42 | Community leaders have the right and responsibility to remove, edit, or reject comments, 43 | commits, code, wiki edits, issues, and other contributions that are not aligned to this 44 | Code of Conduct, and will communicate reasons for moderation decisions when appropriate. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies within all community spaces, and also applies when an 49 | individual is officially representing the community in public spaces. Examples of 50 | representing our community include using an official e-mail address, posting via an 51 | official social media account, or acting as an appointed representative at an online or 52 | offline event. 53 | 54 | ## Enforcement 55 | 56 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to 57 | the community leaders responsible for enforcement at mcp-coc@anthropic.com. All 58 | complaints will be reviewed and investigated promptly and fairly. 59 | 60 | All community leaders are obligated to respect the privacy and security of the reporter 61 | of any incident. 62 | 63 | ## Enforcement Guidelines 64 | 65 | Community leaders will follow these Community Impact Guidelines in determining the 66 | consequences for any action they deem in violation of this Code of Conduct: 67 | 68 | ### 1. Correction 69 | 70 | **Community Impact**: Use of inappropriate language or other behavior deemed 71 | unprofessional or unwelcome in the community. 72 | 73 | **Consequence**: A private, written warning from community leaders, providing clarity 74 | around the nature of the violation and an explanation of why the behavior was 75 | inappropriate. A public apology may be requested. 76 | 77 | ### 2. Warning 78 | 79 | **Community Impact**: A violation through a single incident or series of actions. 80 | 81 | **Consequence**: A warning with consequences for continued behavior. No interaction with 82 | the people involved, including unsolicited interaction with those enforcing the Code of 83 | Conduct, for a specified period of time. This includes avoiding interactions in community 84 | spaces as well as external channels like social media. Violating these terms may lead to 85 | a temporary or permanent ban. 86 | 87 | ### 3. Temporary Ban 88 | 89 | **Community Impact**: A serious violation of community standards, including sustained 90 | inappropriate behavior. 91 | 92 | **Consequence**: A temporary ban from any sort of interaction or public communication 93 | with the community for a specified period of time. No public or private interaction with 94 | the people involved, including unsolicited interaction with those enforcing the Code of 95 | Conduct, is allowed during this period. Violating these terms may lead to a permanent 96 | ban. 97 | 98 | ### 4. Permanent Ban 99 | 100 | **Community Impact**: Demonstrating a pattern of violation of community standards, 101 | including sustained inappropriate behavior, harassment of an individual, or aggression 102 | toward or disparagement of classes of individuals. 103 | 104 | **Consequence**: A permanent ban from any sort of public interaction within the 105 | community. 106 | 107 | ## Attribution 108 | 109 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, 110 | available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. 111 | 112 | Community Impact Guidelines were inspired by 113 | [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). 114 | 115 | [homepage]: https://www.contributor-covenant.org 116 | 117 | For answers to common questions about this code of conduct, see the FAQ at 118 | https://www.contributor-covenant.org/faq. Translations are available at 119 | https://www.contributor-covenant.org/translations. 120 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to Model Context Protocol 2 | 3 | Thank you for your interest in contributing to the Model Context Protocol specification! 4 | This document outlines how to contribute to this project. 5 | 6 | ## Prerequisites 7 | 8 | The following software is required to work on the spec: 9 | 10 | - Node.js 20 or above 11 | - TypeScript 12 | - TypeScript JSON Schema (for generating JSON schema) 13 | - [Mintlify](https://mintlify.com/) (optional, for docs) 14 | - nvm (optional, for managing Node versions) 15 | 16 | ## Getting Started 17 | 18 | 1. Fork the repository 19 | 2. Clone your fork: 20 | 21 | ```bash 22 | git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git 23 | cd modelcontextprotocol 24 | ``` 25 | 26 | 3. Install dependencies: 27 | 28 | ```bash 29 | nvm install # install correct Node version 30 | npm install # install dependencies 31 | ``` 32 | 33 | ## Making Changes 34 | 35 | Note that schema changes are made to `schema.ts`. `schema.json` is generated from 36 | `schema.ts` using `npm run validate:schema`. 37 | 38 | 1. Create a new branch: 39 | 40 | ```bash 41 | git checkout -b feature/your-feature-name 42 | ``` 43 | 44 | 2. Make your changes 45 | 3. Validate your changes: 46 | 47 | ```bash 48 | npm run validate:schema # validate schema 49 | npm run generate:json # generate JSON schema 50 | ``` 51 | 52 | 4. Run docs locally (optional): 53 | 54 | ```bash 55 | npm run serve:docs 56 | ``` 57 | 58 | ### Documentation Guidelines 59 | 60 | When contributing to the documentation: 61 | 62 | - Keep content clear, concise, and technically accurate 63 | - Follow the existing file structure and naming conventions 64 | - Include code examples where appropriate 65 | - Use proper MDX formatting and components 66 | - Test all links and code samples 67 | - Use appropriate headings: "When to use", "Steps", and "Tips" for tutorials 68 | - Place new pages in appropriate sections (concepts, tutorials, etc.) 69 | - Update docs.json when adding new pages 70 | - Follow existing file naming conventions (kebab-case.mdx) 71 | - Include proper frontmatter in MDX files 72 | 73 | ### Specification Proposal Guidelines 74 | 75 | #### Principles of MCP 76 | 77 | 1. **Simple + Minimal**: It is much easier to add things to a specification than it is to 78 | remove them. To maintain simplicity, we keep a high bar for adding new concepts and 79 | primitives as each addition requires maintenance and compatibility consideration. 80 | 2. **Concrete**: Specification changes need to be based on specific implementation 81 | challenges and not on speculative ideas. 82 | 83 | ### Stages of a specification proposal 84 | 85 | 1. **Define**: Explore the problem space, validate that other MCP users face a similar 86 | issue, and then clearly define the problem. 87 | 2. **Prototype**: Build an example solution to the problem and demonstrate its practical 88 | application. 89 | 3. **Write**: Based on the prototype, write a specification proposal. 90 | 91 | ## Submitting Changes 92 | 93 | 1. Push your changes to your fork 94 | 2. Submit a pull request to the main repository 95 | 3. Follow the pull request template 96 | 4. Wait for review 97 | 98 | ## Code of Conduct 99 | 100 | This project follows a Code of Conduct. Please review it in 101 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). 102 | 103 | ## Questions 104 | 105 | If you have questions, please create an issue in the repository. 106 | 107 | ## License 108 | 109 | By contributing, you agree that your contributions will be licensed under the MIT 110 | License. 111 | 112 | ## Security 113 | 114 | Please review our [Security Policy](SECURITY.md) for reporting security issues. 115 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024–2025 Anthropic, PBC and contributors 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Model Context Protocol specification 2 | 3 | This repo contains the specification and protocol schema for the Model Context Protocol. 4 | 5 | The schema is [defined in TypeScript](schema/2025-03-26/schema.ts) first, but 6 | [made available as JSON Schema](schema/2025-03-26/schema.json) as well, for wider 7 | compatibility. 8 | 9 | The official MCP documentation is built using Mintlify and available at 10 | [modelcontextprotocol.io](https://modelcontextprotocol.io). 11 | 12 | ## Contributing 13 | 14 | Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this 15 | project. 16 | 17 | ## License 18 | 19 | This project is licensed under the MIT License—see the [LICENSE](LICENSE) file for 20 | details. 21 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | Thank you for helping us keep the SDKs and systems they interact with secure. 4 | 5 | ## Reporting Security Issues 6 | 7 | This SDK is maintained by [Anthropic](https://www.anthropic.com/) as part of the Model 8 | Context Protocol project. 9 | 10 | The security of our systems and user data is Anthropic’s top priority. We appreciate the 11 | work of security researchers acting in good faith in identifying and reporting potential 12 | vulnerabilities. 13 | 14 | Our security program is managed on HackerOne and we ask that any validated vulnerability 15 | in this functionality be reported through their 16 | [submission form](https://hackerone.com/anthropic-vdp/reports/new?type=team&report_type=vulnerability). 17 | 18 | ## Vulnerability Disclosure Program 19 | 20 | Our Vulnerability Program Guidelines are defined on our 21 | [HackerOne program page](https://hackerone.com/anthropic-vdp). 22 | -------------------------------------------------------------------------------- /docs/development/contributing.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Contributing 3 | description: How to participate in Model Context Protocol development 4 | --- 5 | 6 | We welcome contributions from the community! Please review our [contributing guidelines](https://github.com/modelcontextprotocol/.github/blob/main/CONTRIBUTING.md) for details on how to submit changes. 7 | 8 | All contributors must adhere to our [Code of Conduct](https://github.com/modelcontextprotocol/.github/blob/main/CODE_OF_CONDUCT.md). 9 | 10 | For questions and discussions, please use [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions). 11 | -------------------------------------------------------------------------------- /docs/development/roadmap.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Roadmap 3 | description: Our plans for evolving Model Context Protocol 4 | --- 5 | 6 | Last updated: **2025-03-27** 7 | 8 | The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and direction for approximately **the next six months**, though these may change significantly as the project develops. To see what's changed recently, check out the **[specification changelog](/specification/2025-03-26/changelog/)**. 9 | 10 | The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. This is also not an _exhaustive_ list; we may incorporate work that isn't mentioned here. 11 | 12 | We value community participation! Each section links to relevant discussions where you can learn more and contribute your thoughts. 13 | 14 | For a technical view of our standardization process, visit the [Standards Track](https://github.com/orgs/modelcontextprotocol/projects/2/views/2) on GitHub, which tracks how proposals progress toward inclusion in the official [MCP specification](https://spec.modelcontextprotocol.io). 15 | 16 | ## Validation 17 | 18 | To foster a robust developer ecosystem, we plan to invest in: 19 | 20 | - **Reference Client Implementations**: demonstrating protocol features with high-quality AI applications 21 | - **Compliance Test Suites**: automated verification that clients, servers, and SDKs properly implement the specification 22 | 23 | These tools will help developers confidently implement MCP while ensuring consistent behavior across the ecosystem. 24 | 25 | ## Registry 26 | 27 | For MCP to reach its full potential, we need streamlined ways to distribute and discover MCP servers. 28 | 29 | We plan to develop an [**MCP Registry**](https://github.com/orgs/modelcontextprotocol/discussions/159) that will enable centralized server discovery and metadata. This registry will primarily function as an API layer that third-party marketplaces and discovery services can build upon. 30 | 31 | ## Agents 32 | 33 | As MCP increasingly becomes part of agentic workflows, we're exploring [improvements](https://github.com/modelcontextprotocol/specification/discussions/111) such as: 34 | 35 | - **[Agent Graphs](https://github.com/modelcontextprotocol/specification/discussions/94)**: enabling complex agent topologies through namespacing and graph-aware communication patterns 36 | - **Interactive Workflows**: improving human-in-the-loop experiences with granular permissioning, standardized interaction patterns, and [ways to directly communicate](https://github.com/modelcontextprotocol/specification/issues/97) with the end user 37 | 38 | ## Multimodality 39 | 40 | Supporting the full spectrum of AI capabilities in MCP, including: 41 | 42 | - **Additional Modalities**: video and other media types 43 | - **[Streaming](https://github.com/modelcontextprotocol/specification/issues/117)**: multipart, chunked messages, and bidirectional communication for interactive experiences 44 | 45 | ## Governance 46 | 47 | We're implementing governance structures that prioritize: 48 | 49 | - **Community-Led Development**: fostering a collaborative ecosystem where community members and AI developers can all participate in MCP's evolution, ensuring it serves diverse applications and use cases 50 | - **Transparent Standardization**: establishing clear processes for contributing to the specification, while exploring formal standardization via industry bodies 51 | 52 | ## Get Involved 53 | 54 | We welcome your contributions to MCP's future! Join our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to share ideas, provide feedback, or participate in the development process. 55 | -------------------------------------------------------------------------------- /docs/development/updates.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "What's New" 3 | description: 'The latest updates and improvements to MCP' 4 | --- 5 | 6 | 7 | - Version [0.9.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.9.0) of the MCP Java SDK has been released. 8 | - Refactored logging system to use exchange mechanism 9 | - Custom Context Paths 10 | - Server Instructions 11 | - CallToolResult Enhancement 12 | 13 | 14 | - Fix issues and cleanup API 15 | - Added binary compatibility tracking to avoid breaking changes 16 | - Drop jdk requirements to JDK8 17 | - Added Claude Desktop integration with sample 18 | - The full changelog can be found here: https://github.com/modelcontextprotocol/kotlin-sdk/releases/tag/0.4.0 19 | 20 | 21 | 22 | - Version [0.8.1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.8.1) of the MCP Java SDK has been released, 23 | providing important bug fixes. 24 | 25 | 26 | - We are exited to announce the availability of the MCP 27 | [C# SDK](https://github.com/modelcontextprotocol/csharp-sdk/) developed by 28 | [Peder Holdgaard Pedersen](http://github.com/PederHP) and Microsoft. This joins our growing 29 | list of supported languages. The C# SDK is also available as 30 | [NuGet package](https://www.nuget.org/packages/ModelContextProtocol) 31 | - Python SDK 1.5.0 was released with multiple fixes and improvements. 32 | 33 | 34 | - Version [0.8.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.8.0) of the MCP Java SDK has been released, 35 | delivering important session management improvements and bug fixes. 36 | 37 | 38 | - Typescript SDK 1.7.0 was released with multiple fixes and improvements. 39 | 40 | 41 | - We're excited to announce that the Java SDK developed by Spring AI at VMware Tanzu is now 42 | the official [Java SDK](https://github.com/modelcontextprotocol/java-sdk) for MCP. 43 | This joins our existing Kotlin SDK in our growing list of supported languages. 44 | The Spring AI team will maintain the SDK as an integral part of the Model Context Protocol 45 | organization. We're thrilled to welcome them to the MCP community! 46 | 47 | 48 | 49 | - Version [1.2.1](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.2.1) of the MCP Python SDK has been released, 50 | delivering important stability improvements and bug fixes. 51 | 52 | 53 | - Simplified, express-like API in the [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) 54 | - Added 8 new clients to the [clients page](https://modelcontextprotocol.io/clients) 55 | 56 | 57 | 58 | - FastMCP API in the [Python SDK](https://github.com/modelcontextprotocol/python-sdk) 59 | - Dockerized MCP servers in the [servers repo](https://github.com/modelcontextprotocol/servers) 60 | 61 | 62 | 63 | - Jetbrains released a Kotlin SDK for MCP! 64 | - For a sample MCP Kotlin server, check out [this repository](https://github.com/modelcontextprotocol/kotlin-sdk/tree/main/samples/kotlin-mcp-server) 65 | 66 | -------------------------------------------------------------------------------- /docs/docs/concepts/roots.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Roots" 3 | description: "Understanding roots in MCP" 4 | --- 5 | 6 | Roots are a concept in MCP that define the boundaries where servers can operate. They provide a way for clients to inform servers about relevant resources and their locations. 7 | 8 | ## What are Roots? 9 | 10 | A root is a URI that a client suggests a server should focus on. When a client connects to a server, it declares which roots the server should work with. While primarily used for filesystem paths, roots can be any valid URI including HTTP URLs. 11 | 12 | For example, roots could be: 13 | 14 | ``` 15 | file:///home/user/projects/myapp 16 | https://api.example.com/v1 17 | ``` 18 | 19 | ## Why Use Roots? 20 | 21 | Roots serve several important purposes: 22 | 23 | 1. **Guidance**: They inform servers about relevant resources and locations 24 | 2. **Clarity**: Roots make it clear which resources are part of your workspace 25 | 3. **Organization**: Multiple roots let you work with different resources simultaneously 26 | 27 | ## How Roots Work 28 | 29 | When a client supports roots, it: 30 | 31 | 1. Declares the `roots` capability during connection 32 | 2. Provides a list of suggested roots to the server 33 | 3. Notifies the server when roots change (if supported) 34 | 35 | While roots are informational and not strictly enforcing, servers should: 36 | 37 | 1. Respect the provided roots 38 | 2. Use root URIs to locate and access resources 39 | 3. Prioritize operations within root boundaries 40 | 41 | ## Common Use Cases 42 | 43 | Roots are commonly used to define: 44 | 45 | - Project directories 46 | - Repository locations 47 | - API endpoints 48 | - Configuration locations 49 | - Resource boundaries 50 | 51 | ## Best Practices 52 | 53 | When working with roots: 54 | 55 | 1. Only suggest necessary resources 56 | 2. Use clear, descriptive names for roots 57 | 3. Monitor root accessibility 58 | 4. Handle root changes gracefully 59 | 60 | ## Example 61 | 62 | Here's how a typical MCP client might expose roots: 63 | 64 | ```json 65 | { 66 | "roots": [ 67 | { 68 | "uri": "file:///home/user/projects/frontend", 69 | "name": "Frontend Repository" 70 | }, 71 | { 72 | "uri": "https://api.example.com/v1", 73 | "name": "API Endpoint" 74 | } 75 | ] 76 | } 77 | ``` 78 | 79 | This configuration suggests the server focus on both a local repository and an API endpoint while keeping them logically separated. -------------------------------------------------------------------------------- /docs/docs/tools/inspector.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Inspector 3 | description: In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers 4 | --- 5 | 6 | The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](/docs/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. 7 | 8 | ## Getting started 9 | 10 | ### Installation and basic usage 11 | 12 | The Inspector runs directly through `npx` without requiring installation: 13 | 14 | 15 | ```bash 16 | npx @modelcontextprotocol/inspector 17 | ``` 18 | 19 | ```bash 20 | npx @modelcontextprotocol/inspector 21 | ``` 22 | 23 | #### Inspecting servers from NPM or PyPi 24 | 25 | A common way to start server packages from [NPM](https://npmjs.com) or [PyPi](https://pypi.com). 26 | 27 | 28 | 29 | 30 | ```bash 31 | npx -y @modelcontextprotocol/inspector npx 32 | # For example 33 | npx -y @modelcontextprotocol/inspector npx server-postgres postgres://127.0.0.1/testdb 34 | ``` 35 | 36 | 37 | 38 | ```bash 39 | npx @modelcontextprotocol/inspector uvx 40 | # For example 41 | npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git 42 | ``` 43 | 44 | 45 | 46 | #### Inspecting locally developed servers 47 | 48 | To inspect servers locally developed or downloaded as a repository, the most common 49 | way is: 50 | 51 | 52 | 53 | ```bash 54 | npx @modelcontextprotocol/inspector node path/to/server/index.js args... 55 | ``` 56 | 57 | 58 | ```bash 59 | npx @modelcontextprotocol/inspector \ 60 | uv \ 61 | --directory path/to/server \ 62 | run \ 63 | package-name \ 64 | args... 65 | ``` 66 | 67 | 68 | 69 | Please carefully read any attached README for the most accurate instructions. 70 | 71 | ## Feature overview 72 | 73 | 74 | 75 | 76 | 77 | The Inspector provides several features for interacting with your MCP server: 78 | 79 | ### Server connection pane 80 | - Allows selecting the [transport](/docs/concepts/transports) for connecting to the server 81 | - For local servers, supports customizing the command-line arguments and environment 82 | 83 | ### Resources tab 84 | - Lists all available resources 85 | - Shows resource metadata (MIME types, descriptions) 86 | - Allows resource content inspection 87 | - Supports subscription testing 88 | 89 | ### Prompts tab 90 | - Displays available prompt templates 91 | - Shows prompt arguments and descriptions 92 | - Enables prompt testing with custom arguments 93 | - Previews generated messages 94 | 95 | ### Tools tab 96 | - Lists available tools 97 | - Shows tool schemas and descriptions 98 | - Enables tool testing with custom inputs 99 | - Displays tool execution results 100 | 101 | ### Notifications pane 102 | - Presents all logs recorded from the server 103 | - Shows notifications received from the server 104 | 105 | ## Best practices 106 | 107 | ### Development workflow 108 | 109 | 1. Start Development 110 | - Launch Inspector with your server 111 | - Verify basic connectivity 112 | - Check capability negotiation 113 | 114 | 2. Iterative testing 115 | - Make server changes 116 | - Rebuild the server 117 | - Reconnect the Inspector 118 | - Test affected features 119 | - Monitor messages 120 | 121 | 3. Test edge cases 122 | - Invalid inputs 123 | - Missing prompt arguments 124 | - Concurrent operations 125 | - Verify error handling and error responses 126 | 127 | ## Next steps 128 | 129 | 130 | 135 | Check out the MCP Inspector source code 136 | 137 | 138 | 143 | Learn about broader debugging strategies 144 | 145 | 146 | -------------------------------------------------------------------------------- /docs/examples.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Example Servers 3 | description: 'A list of example servers and implementations' 4 | --- 5 | 6 | This page showcases various Model Context Protocol (MCP) servers that demonstrate the protocol's capabilities and versatility. These servers enable Large Language Models (LLMs) to securely access tools and data sources. 7 | 8 | ## Reference implementations 9 | 10 | These official reference servers demonstrate core MCP features and SDK usage: 11 | 12 | ### Data and file systems 13 | - **[Filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)** - Secure file operations with configurable access controls 14 | - **[PostgreSQL](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres)** - Read-only database access with schema inspection capabilities 15 | - **[SQLite](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite)** - Database interaction and business intelligence features 16 | - **[Google Drive](https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive)** - File access and search capabilities for Google Drive 17 | 18 | ### Development tools 19 | - **[Git](https://github.com/modelcontextprotocol/servers/tree/main/src/git)** - Tools to read, search, and manipulate Git repositories 20 | - **[GitHub](https://github.com/modelcontextprotocol/servers/tree/main/src/github)** - Repository management, file operations, and GitHub API integration 21 | - **[GitLab](https://github.com/modelcontextprotocol/servers/tree/main/src/gitlab)** - GitLab API integration enabling project management 22 | - **[Sentry](https://github.com/modelcontextprotocol/servers/tree/main/src/sentry)** - Retrieving and analyzing issues from Sentry.io 23 | 24 | ### Web and browser automation 25 | - **[Brave Search](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)** - Web and local search using Brave's Search API 26 | - **[Fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch)** - Web content fetching and conversion optimized for LLM usage 27 | - **[Puppeteer](https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer)** - Browser automation and web scraping capabilities 28 | 29 | ### Productivity and communication 30 | - **[Slack](https://github.com/modelcontextprotocol/servers/tree/main/src/slack)** - Channel management and messaging capabilities 31 | - **[Google Maps](https://github.com/modelcontextprotocol/servers/tree/main/src/google-maps)** - Location services, directions, and place details 32 | - **[Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory)** - Knowledge graph-based persistent memory system 33 | 34 | ### AI and specialized tools 35 | - **[EverArt](https://github.com/modelcontextprotocol/servers/tree/main/src/everart)** - AI image generation using various models 36 | - **[Sequential Thinking](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)** - Dynamic problem-solving through thought sequences 37 | - **[AWS KB Retrieval](https://github.com/modelcontextprotocol/servers/tree/main/src/aws-kb-retrieval-server)** - Retrieval from AWS Knowledge Base using Bedrock Agent Runtime 38 | 39 | ## Official integrations 40 | 41 | Visit the [MCP Servers Repository (Official Integrations section)](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#%EF%B8%8F-official-integrations) for a list of MCP servers maintained by companies for their platforms. 42 | 43 | ## Community implementations 44 | 45 | Visit the [MCP Servers Repository (Community section)](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#-community-servers) for a list of MCP servers maintained by community members. 46 | 47 | ## Getting started 48 | 49 | ### Using reference servers 50 | 51 | TypeScript-based servers can be used directly with `npx`: 52 | 53 | ```bash 54 | npx -y @modelcontextprotocol/server-memory 55 | ``` 56 | 57 | Python-based servers can be used with `uvx` (recommended) or `pip`: 58 | 59 | ```bash 60 | # Using uvx 61 | uvx mcp-server-git 62 | 63 | # Using pip 64 | pip install mcp-server-git 65 | python -m mcp_server_git 66 | ``` 67 | 68 | ### Configuring with Claude 69 | 70 | To use an MCP server with Claude, add it to your configuration: 71 | 72 | ```json 73 | { 74 | "mcpServers": { 75 | "memory": { 76 | "command": "npx", 77 | "args": ["-y", "@modelcontextprotocol/server-memory"] 78 | }, 79 | "filesystem": { 80 | "command": "npx", 81 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] 82 | }, 83 | "github": { 84 | "command": "npx", 85 | "args": ["-y", "@modelcontextprotocol/server-github"], 86 | "env": { 87 | "GITHUB_PERSONAL_ACCESS_TOKEN": "" 88 | } 89 | } 90 | } 91 | } 92 | ``` 93 | 94 | ## Additional resources 95 | 96 | Visit the [MCP Servers Repository (Resources section)](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#-resources) for a collection of other resources and projects related to MCP. 97 | 98 | Visit our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to engage with the MCP community. 99 | -------------------------------------------------------------------------------- /docs/faqs.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "FAQs" 3 | description: "Explaining MCP and why it matters in simple terms" 4 | --- 5 | 6 | ## What is MCP? 7 | 8 | MCP (Model Context Protocol) is a standard way for AI applications and agents to connect to and work with your data sources (e.g. local files, databases, or content repositories) and tools (e.g. GitHub, Google Maps, or Puppeteer). 9 | 10 | Think of MCP as a universal adapter for AI applications, similar to what USB-C is for physical devices. USB-C acts as a universal adapter to connect devices to various peripherals and accessories. Similarly, MCP provides a standardized way to connect AI applications to different data and tools. 11 | 12 | Before USB-C, you needed different cables for different connections. Similarly, before MCP, developers had to build custom connections to each data source or tool they wanted their AI application to work with—a time-consuming process that often resulted in limited functionality. Now, with MCP, developers can easily add connections to their AI applications, making their applications much more powerful from day one. 13 | 14 | ## Why does MCP matter? 15 | 16 | ### For AI application users 17 | 18 | MCP means your AI applications can access the information and tools you work with every day, making them much more helpful. Rather than AI being limited to what it already knows about, it can now understand your specific documents, data, and work context. 19 | 20 | For example, by using MCP servers, applications can access your personal documents from Google Drive or data about your codebase from GitHub, providing more personalized and contextually relevant assistance. 21 | 22 | Imagine asking an AI assistant: "Summarize last week's team meeting notes and schedule follow-ups with everyone." 23 | 24 | By using connections to data sources powered by MCP, the AI assistant can: 25 | 26 | - Connect to your Google Drive through an MCP server to read meeting notes 27 | - Understand who needs follow-ups based on the notes 28 | - Connect to your calendar through another MCP server to schedule the meetings automatically 29 | 30 | ### For developers 31 | 32 | MCP reduces development time and complexity when building AI applications that need to access various data sources. With MCP, developers can focus on building great AI experiences rather than repeatedly creating custom connectors. 33 | 34 | Traditionally, connecting applications with data sources required building custom, one-off connections for each data source and each application. This created significant duplicative work—every developer wanting to connect their AI application to Google Drive or Slack needed to build their own connection. 35 | 36 | MCP simplifies this by enabling developers to build MCP servers for data sources that are then reusable by various applications. For example, using the open source Google Drive MCP server, many different applications can access data from Google Drive without each developer needing to build a custom connection. 37 | 38 | This open source ecosystem of MCP servers means developers can leverage existing work rather than starting from scratch, making it easier to build powerful AI applications that seamlessly integrate with the tools and data sources their users already rely on. 39 | 40 | ## How does MCP work? 41 | 42 | 43 | 44 | 45 | 46 | MCP creates a bridge between your AI applications and your data through a straightforward system: 47 | 48 | - **MCP servers** connect to your data sources and tools (like Google Drive or Slack) 49 | - **MCP clients** are run by AI applications (like Claude Desktop) to connect them to these servers 50 | - When you give permission, your AI application discovers available MCP servers 51 | - The AI model can then use these connections to read information and take actions 52 | 53 | This modular system means new capabilities can be added without changing AI applications themselves—just like adding new accessories to your computer without upgrading your entire system. 54 | 55 | ## Who creates and maintains MCP servers? 56 | 57 | MCP servers are developed and maintained by: 58 | 59 | - Developers at Anthropic who build servers for common tools and data sources 60 | - Open source contributors who create servers for tools they use 61 | - Enterprise development teams building servers for their internal systems 62 | - Software providers making their applications AI-ready 63 | 64 | Once an open source MCP server is created for a data source, it can be used by any MCP-compatible AI application, creating a growing ecosystem of connections. See our [list of example servers](https://modelcontextprotocol.io/examples), or [get started building your own server](https://modelcontextprotocol.io/quickstart/server). -------------------------------------------------------------------------------- /docs/favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /docs/images/available-mcp-tools.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/available-mcp-tools.png -------------------------------------------------------------------------------- /docs/images/claude-desktop-mcp-plug-icon.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | -------------------------------------------------------------------------------- /docs/images/claude-desktop-mcp-slider.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | -------------------------------------------------------------------------------- /docs/images/client-claude-cli-python.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/client-claude-cli-python.png -------------------------------------------------------------------------------- /docs/images/current-weather.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/current-weather.png -------------------------------------------------------------------------------- /docs/images/java/java-mcp-client-architecture.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/java/java-mcp-client-architecture.jpg -------------------------------------------------------------------------------- /docs/images/java/java-mcp-server-architecture.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/java/java-mcp-server-architecture.jpg -------------------------------------------------------------------------------- /docs/images/mcp-inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/mcp-inspector.png -------------------------------------------------------------------------------- /docs/images/mcp-simple-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/mcp-simple-diagram.png -------------------------------------------------------------------------------- /docs/images/og-image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/og-image.png -------------------------------------------------------------------------------- /docs/images/quickstart-approve.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/quickstart-approve.png -------------------------------------------------------------------------------- /docs/images/quickstart-developer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/quickstart-developer.png -------------------------------------------------------------------------------- /docs/images/quickstart-dotnet-client.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/quickstart-dotnet-client.png -------------------------------------------------------------------------------- /docs/images/quickstart-filesystem.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/quickstart-filesystem.png -------------------------------------------------------------------------------- /docs/images/quickstart-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/quickstart-menu.png -------------------------------------------------------------------------------- /docs/images/quickstart-screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/quickstart-screenshot.png -------------------------------------------------------------------------------- /docs/images/quickstart-slider.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/quickstart-slider.png -------------------------------------------------------------------------------- /docs/images/quickstart-tools.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/quickstart-tools.png -------------------------------------------------------------------------------- /docs/images/visual-indicator-mcp-tools.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/visual-indicator-mcp-tools.png -------------------------------------------------------------------------------- /docs/images/weather-alerts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/images/weather-alerts.png -------------------------------------------------------------------------------- /docs/introduction.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Introduction 3 | description: 'Get started with the Model Context Protocol (MCP)' 4 | --- 5 | 6 | C# SDK released! Check out [what else is new.](/development/updates) 7 | 8 | MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. 9 | 10 | ## Why MCP? 11 | 12 | MCP helps you build agents and complex workflows on top of LLMs. LLMs frequently need to integrate with data and tools, and MCP provides: 13 | - A growing list of pre-built integrations that your LLM can directly plug into 14 | - The flexibility to switch between LLM providers and vendors 15 | - Best practices for securing your data within your infrastructure 16 | 17 | ### General architecture 18 | 19 | At its core, MCP follows a client-server architecture where a host application can connect to multiple servers: 20 | 21 | ```mermaid 22 | flowchart LR 23 | subgraph "Your Computer" 24 | Host["Host with MCP Client\n(Claude, IDEs, Tools)"] 25 | S1["MCP Server A"] 26 | S2["MCP Server B"] 27 | S3["MCP Server C"] 28 | Host <-->|"MCP Protocol"| S1 29 | Host <-->|"MCP Protocol"| S2 30 | Host <-->|"MCP Protocol"| S3 31 | S1 <--> D1[("Local\nData Source A")] 32 | S2 <--> D2[("Local\nData Source B")] 33 | end 34 | subgraph "Internet" 35 | S3 <-->|"Web APIs"| D3[("Remote\nService C")] 36 | end 37 | ``` 38 | 39 | - **MCP Hosts**: Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP 40 | - **MCP Clients**: Protocol clients that maintain 1:1 connections with servers 41 | - **MCP Servers**: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol 42 | - **Local Data Sources**: Your computer's files, databases, and services that MCP servers can securely access 43 | - **Remote Services**: External systems available over the internet (e.g., through APIs) that MCP servers can connect to 44 | 45 | ## Get started 46 | 47 | Choose the path that best fits your needs: 48 | 49 | #### Quick Starts 50 | 51 | 56 | Get started building your own server to use in Claude for Desktop and other clients 57 | 58 | 63 | Get started building your own client that can integrate with all MCP servers 64 | 65 | 70 | Get started using pre-built servers in Claude for Desktop 71 | 72 | 73 | 74 | #### Examples 75 | 76 | 81 | Check out our gallery of official MCP servers and implementations 82 | 83 | 88 | View the list of clients that support MCP integrations 89 | 90 | 91 | 92 | ## Tutorials 93 | 94 | 95 | 100 | Learn how to use LLMs like Claude to speed up your MCP development 101 | 102 | 106 | Learn how to effectively debug MCP servers and integrations 107 | 108 | 113 | Test and inspect your MCP servers with our interactive debugging tool 114 | 115 | 120 | 121 | 122 | 123 | 124 | ## Explore MCP 125 | 126 | Dive deeper into MCP's core concepts and capabilities: 127 | 128 | 129 | 134 | Understand how MCP connects clients, servers, and LLMs 135 | 136 | 141 | Expose data and content from your servers to LLMs 142 | 143 | 148 | Create reusable prompt templates and workflows 149 | 150 | 155 | Enable LLMs to perform actions through your server 156 | 157 | 162 | Let your servers request completions from LLMs 163 | 164 | 169 | Learn about MCP's communication mechanism 170 | 171 | 172 | 173 | ## Contributing 174 | 175 | Want to contribute? Check out our [Contributing Guide](/development/contributing) to learn how you can help improve MCP. 176 | 177 | ## Support and Feedback 178 | 179 | Here's how to get help or provide feedback: 180 | 181 | - For bug reports and feature requests related to the MCP specification, SDKs, or documentation (open source), please [create a GitHub issue](https://github.com/modelcontextprotocol) 182 | - For discussions or Q&A about the MCP specification, use the [specification discussions](https://github.com/modelcontextprotocol/specification/discussions) 183 | - For discussions or Q&A about other MCP open source components, use the [organization discussions](https://github.com/orgs/modelcontextprotocol/discussions) 184 | - For bug reports, feature requests, and questions related to Claude.app and claude.ai's MCP integration, please see Anthropic's guide on [How to Get Support](https://support.anthropic.com/en/articles/9015913-how-to-get-support) 185 | -------------------------------------------------------------------------------- /docs/logo/dark.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/logo/dark.png -------------------------------------------------------------------------------- /docs/logo/light.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/logo/light.png -------------------------------------------------------------------------------- /docs/snippets/snippet-intro.mdx: -------------------------------------------------------------------------------- 1 | One of the core principles of software development is DRY (Don't Repeat 2 | Yourself). This is a principle that apply to documentation as 3 | well. If you find yourself repeating the same content in multiple places, you 4 | should consider creating a custom snippet to keep your content in sync. 5 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/architecture/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Architecture 3 | --- 4 | 5 | The Model Context Protocol (MCP) follows a client-host-server architecture where each 6 | host can run multiple client instances. This architecture enables users to integrate AI 7 | capabilities across applications while maintaining clear security boundaries and 8 | isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused 9 | on context exchange and sampling coordination between clients and servers. 10 | 11 | ## Core Components 12 | 13 | ```mermaid 14 | graph LR 15 | subgraph "Application Host Process" 16 | H[Host] 17 | C1[Client 1] 18 | C2[Client 2] 19 | C3[Client 3] 20 | H --> C1 21 | H --> C2 22 | H --> C3 23 | end 24 | 25 | subgraph "Local machine" 26 | S1[Server 1
Files & Git] 27 | S2[Server 2
Database] 28 | R1[("Local
Resource A")] 29 | R2[("Local
Resource B")] 30 | 31 | C1 --> S1 32 | C2 --> S2 33 | S1 <--> R1 34 | S2 <--> R2 35 | end 36 | 37 | subgraph "Internet" 38 | S3[Server 3
External APIs] 39 | R3[("Remote
Resource C")] 40 | 41 | C3 --> S3 42 | S3 <--> R3 43 | end 44 | ``` 45 | 46 | ### Host 47 | 48 | The host process acts as the container and coordinator: 49 | 50 | - Creates and manages multiple client instances 51 | - Controls client connection permissions and lifecycle 52 | - Enforces security policies and consent requirements 53 | - Handles user authorization decisions 54 | - Coordinates AI/LLM integration and sampling 55 | - Manages context aggregation across clients 56 | 57 | ### Clients 58 | 59 | Each client is created by the host and maintains an isolated server connection: 60 | 61 | - Establishes one stateful session per server 62 | - Handles protocol negotiation and capability exchange 63 | - Routes protocol messages bidirectionally 64 | - Manages subscriptions and notifications 65 | - Maintains security boundaries between servers 66 | 67 | A host application creates and manages multiple clients, with each client having a 1:1 68 | relationship with a particular server. 69 | 70 | ### Servers 71 | 72 | Servers provide specialized context and capabilities: 73 | 74 | - Expose resources, tools and prompts via MCP primitives 75 | - Operate independently with focused responsibilities 76 | - Request sampling through client interfaces 77 | - Must respect security constraints 78 | - Can be local processes or remote services 79 | 80 | ## Design Principles 81 | 82 | MCP is built on several key design principles that inform its architecture and 83 | implementation: 84 | 85 | 1. **Servers should be extremely easy to build** 86 | 87 | - Host applications handle complex orchestration responsibilities 88 | - Servers focus on specific, well-defined capabilities 89 | - Simple interfaces minimize implementation overhead 90 | - Clear separation enables maintainable code 91 | 92 | 2. **Servers should be highly composable** 93 | 94 | - Each server provides focused functionality in isolation 95 | - Multiple servers can be combined seamlessly 96 | - Shared protocol enables interoperability 97 | - Modular design supports extensibility 98 | 99 | 3. **Servers should not be able to read the whole conversation, nor "see into" other 100 | servers** 101 | 102 | - Servers receive only necessary contextual information 103 | - Full conversation history stays with the host 104 | - Each server connection maintains isolation 105 | - Cross-server interactions are controlled by the host 106 | - Host process enforces security boundaries 107 | 108 | 4. **Features can be added to servers and clients progressively** 109 | - Core protocol provides minimal required functionality 110 | - Additional capabilities can be negotiated as needed 111 | - Servers and clients evolve independently 112 | - Protocol designed for future extensibility 113 | - Backwards compatibility is maintained 114 | 115 | ## Message Types 116 | 117 | MCP defines three core message types based on 118 | [JSON-RPC 2.0](https://www.jsonrpc.org/specification): 119 | 120 | - **Requests**: Bidirectional messages with method and parameters expecting a response 121 | - **Responses**: Successful results or errors matching specific request IDs 122 | - **Notifications**: One-way messages requiring no response 123 | 124 | Each message type follows the JSON-RPC 2.0 specification for structure and delivery 125 | semantics. 126 | 127 | ## Capability Negotiation 128 | 129 | The Model Context Protocol uses a capability-based negotiation system where clients and 130 | servers explicitly declare their supported features during initialization. Capabilities 131 | determine which protocol features and primitives are available during a session. 132 | 133 | - Servers declare capabilities like resource subscriptions, tool support, and prompt 134 | templates 135 | - Clients declare capabilities like sampling support and notification handling 136 | - Both parties must respect declared capabilities throughout the session 137 | - Additional capabilities can be negotiated through extensions to the protocol 138 | 139 | ```mermaid 140 | sequenceDiagram 141 | participant Host 142 | participant Client 143 | participant Server 144 | 145 | Host->>+Client: Initialize client 146 | Client->>+Server: Initialize session with capabilities 147 | Server-->>Client: Respond with supported capabilities 148 | 149 | Note over Host,Server: Active Session with Negotiated Features 150 | 151 | loop Client Requests 152 | Host->>Client: User- or model-initiated action 153 | Client->>Server: Request (tools/resources) 154 | Server-->>Client: Response 155 | Client-->>Host: Update UI or respond to model 156 | end 157 | 158 | loop Server Requests 159 | Server->>Client: Request (sampling) 160 | Client->>Host: Forward to AI 161 | Host-->>Client: AI response 162 | Client-->>Server: Response 163 | end 164 | 165 | loop Notifications 166 | Server--)Client: Resource updates 167 | Client--)Server: Status changes 168 | end 169 | 170 | Host->>Client: Terminate 171 | Client->>-Server: End session 172 | deactivate Server 173 | ``` 174 | 175 | Each capability unlocks specific protocol features for use during the session. For 176 | example: 177 | 178 | - Implemented [server features](/specification/2024-11-05/server) must be 179 | advertised in the server's capabilities 180 | - Emitting resource subscription notifications requires the server to declare 181 | subscription support 182 | - Tool invocation requires the server to declare tool capabilities 183 | - [Sampling](/specification/2024-11-05/client) requires the client to 184 | declare support in its capabilities 185 | 186 | This capability negotiation ensures clients and servers have a clear understanding of 187 | supported functionality while maintaining protocol extensibility. 188 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/basic/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overview 3 | --- 4 | 5 | **Protocol Revision**: 2024-11-05 6 | 7 | All messages between MCP clients and servers **MUST** follow the 8 | [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines 9 | three fundamental types of messages: 10 | 11 | | Type | Description | Requirements | 12 | | --------------- | -------------------------------------- | -------------------------------------- | 13 | | `Requests` | Messages sent to initiate an operation | Must include unique ID and method name | 14 | | `Responses` | Messages sent in reply to requests | Must include same ID as request | 15 | | `Notifications` | One-way messages with no reply | Must not include an ID | 16 | 17 | **Responses** are further sub-categorized as either **successful results** or **errors**. 18 | Results can follow any JSON object structure, while errors must include an error code and 19 | message at minimum. 20 | 21 | ## Protocol Layers 22 | 23 | The Model Context Protocol consists of several key components that work together: 24 | 25 | - **Base Protocol**: Core JSON-RPC message types 26 | - **Lifecycle Management**: Connection initialization, capability negotiation, and 27 | session control 28 | - **Server Features**: Resources, prompts, and tools exposed by servers 29 | - **Client Features**: Sampling and root directory lists provided by clients 30 | - **Utilities**: Cross-cutting concerns like logging and argument completion 31 | 32 | All implementations **MUST** support the base protocol and lifecycle management 33 | components. Other components **MAY** be implemented based on the specific needs of the 34 | application. 35 | 36 | These protocol layers establish clear separation of concerns while enabling rich 37 | interactions between clients and servers. The modular design allows implementations to 38 | support exactly the features they need. 39 | 40 | See the following pages for more details on the different components: 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | ## Auth 52 | 53 | Authentication and authorization are not currently part of the core MCP specification, 54 | but we are considering ways to introduce them in future. Join us in 55 | [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions) 56 | to help shape the future of the protocol! 57 | 58 | Clients and servers **MAY** negotiate their own custom authentication and authorization 59 | strategies. 60 | 61 | ## Schema 62 | 63 | The full specification of the protocol is defined as a 64 | [TypeScript schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2024-11-05/schema.ts). 65 | This is the source of truth for all protocol messages and structures. 66 | 67 | There is also a 68 | [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2024-11-05/schema.json), 69 | which is automatically generated from the TypeScript source of truth, for use with 70 | various automated tooling. 71 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/basic/messages.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Messages 3 | type: docs 4 | weight: 20 5 | --- 6 | 7 | **Protocol Revision**: 2024-11-05 8 | 9 | All messages in MCP **MUST** follow the 10 | [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines 11 | three types of messages: 12 | 13 | ## Requests 14 | 15 | Requests are sent from the client to the server or vice versa. 16 | 17 | ```typescript 18 | { 19 | jsonrpc: "2.0"; 20 | id: string | number; 21 | method: string; 22 | params?: { 23 | [key: string]: unknown; 24 | }; 25 | } 26 | ``` 27 | 28 | - Requests **MUST** include a string or integer ID. 29 | - Unlike base JSON-RPC, the ID **MUST NOT** be `null`. 30 | - The request ID **MUST NOT** have been previously used by the requestor within the same 31 | session. 32 | 33 | ## Responses 34 | 35 | Responses are sent in reply to requests. 36 | 37 | ```typescript 38 | { 39 | jsonrpc: "2.0"; 40 | id: string | number; 41 | result?: { 42 | [key: string]: unknown; 43 | } 44 | error?: { 45 | code: number; 46 | message: string; 47 | data?: unknown; 48 | } 49 | } 50 | ``` 51 | 52 | - Responses **MUST** include the same ID as the request they correspond to. 53 | - Either a `result` or an `error` **MUST** be set. A response **MUST NOT** set both. 54 | - Error codes **MUST** be integers. 55 | 56 | ## Notifications 57 | 58 | Notifications are sent from the client to the server or vice versa. They do not expect a 59 | response. 60 | 61 | ```typescript 62 | { 63 | jsonrpc: "2.0"; 64 | method: string; 65 | params?: { 66 | [key: string]: unknown; 67 | }; 68 | } 69 | ``` 70 | 71 | - Notifications **MUST NOT** include an ID. 72 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/basic/transports.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Transports 3 | type: docs 4 | weight: 40 5 | --- 6 | 7 | **Protocol Revision**: 2024-11-05 8 | 9 | MCP currently defines two standard transport mechanisms for client-server communication: 10 | 11 | 1. [stdio](#stdio), communication over standard in and standard out 12 | 2. [HTTP with Server-Sent Events](#http-with-sse) (SSE) 13 | 14 | Clients **SHOULD** support stdio whenever possible. 15 | 16 | It is also possible for clients and servers to implement 17 | [custom transports](#custom-transports) in a pluggable fashion. 18 | 19 | ## stdio 20 | 21 | In the **stdio** transport: 22 | 23 | - The client launches the MCP server as a subprocess. 24 | - The server receives JSON-RPC messages on its standard input (`stdin`) and writes 25 | responses to its standard output (`stdout`). 26 | - Messages are delimited by newlines, and **MUST NOT** contain embedded newlines. 27 | - The server **MAY** write UTF-8 strings to its standard error (`stderr`) for logging 28 | purposes. Clients **MAY** capture, forward, or ignore this logging. 29 | - The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message. 30 | - The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP 31 | message. 32 | 33 | ```mermaid 34 | sequenceDiagram 35 | participant Client 36 | participant Server Process 37 | 38 | Client->>+Server Process: Launch subprocess 39 | loop Message Exchange 40 | Client->>Server Process: Write to stdin 41 | Server Process->>Client: Write to stdout 42 | Server Process--)Client: Optional logs on stderr 43 | end 44 | Client->>Server Process: Close stdin, terminate subprocess 45 | deactivate Server Process 46 | ``` 47 | 48 | ## HTTP with SSE 49 | 50 | In the **SSE** transport, the server operates as an independent process that can handle 51 | multiple client connections. 52 | 53 | #### Security Warning 54 | 55 | When implementing HTTP with SSE transport: 56 | 57 | 1. Servers **MUST** validate the `Origin` header on all incoming connections to prevent DNS rebinding attacks 58 | 2. When running locally, servers **SHOULD** bind only to localhost (127.0.0.1) rather than all network interfaces (0.0.0.0) 59 | 3. Servers **SHOULD** implement proper authentication for all connections 60 | 61 | Without these protections, attackers could use DNS rebinding to interact with local MCP servers from remote websites. 62 | 63 | The server **MUST** provide two endpoints: 64 | 65 | 1. An SSE endpoint, for clients to establish a connection and receive messages from the 66 | server 67 | 2. A regular HTTP POST endpoint for clients to send messages to the server 68 | 69 | When a client connects, the server **MUST** send an `endpoint` event containing a URI for 70 | the client to use for sending messages. All subsequent client messages **MUST** be sent 71 | as HTTP POST requests to this endpoint. 72 | 73 | Server messages are sent as SSE `message` events, with the message content encoded as 74 | JSON in the event data. 75 | 76 | ```mermaid 77 | sequenceDiagram 78 | participant Client 79 | participant Server 80 | 81 | Client->>Server: Open SSE connection 82 | Server->>Client: endpoint event 83 | loop Message Exchange 84 | Client->>Server: HTTP POST messages 85 | Server->>Client: SSE message events 86 | end 87 | Client->>Server: Close SSE connection 88 | ``` 89 | 90 | ## Custom Transports 91 | 92 | Clients and servers **MAY** implement additional custom transport mechanisms to suit 93 | their specific needs. The protocol is transport-agnostic and can be implemented over any 94 | communication channel that supports bidirectional message exchange. 95 | 96 | Implementers who choose to support custom transports **MUST** ensure they preserve the 97 | JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports 98 | **SHOULD** document their specific connection establishment and message exchange patterns 99 | to aid interoperability. 100 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/basic/utilities/cancellation.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Cancellation 3 | weight: 10 4 | --- 5 | 6 | **Protocol Revision**: 2024-11-05 7 | 8 | The Model Context Protocol (MCP) supports optional cancellation of in-progress requests 9 | through notification messages. Either side can send a cancellation notification to 10 | indicate that a previously-issued request should be terminated. 11 | 12 | ## Cancellation Flow 13 | 14 | When a party wants to cancel an in-progress request, it sends a `notifications/cancelled` 15 | notification containing: 16 | 17 | - The ID of the request to cancel 18 | - An optional reason string that can be logged or displayed 19 | 20 | ```json 21 | { 22 | "jsonrpc": "2.0", 23 | "method": "notifications/cancelled", 24 | "params": { 25 | "requestId": "123", 26 | "reason": "User requested cancellation" 27 | } 28 | } 29 | ``` 30 | 31 | ## Behavior Requirements 32 | 33 | 1. Cancellation notifications **MUST** only reference requests that: 34 | - Were previously issued in the same direction 35 | - Are believed to still be in-progress 36 | 2. The `initialize` request **MUST NOT** be cancelled by clients 37 | 3. Receivers of cancellation notifications **SHOULD**: 38 | - Stop processing the cancelled request 39 | - Free associated resources 40 | - Not send a response for the cancelled request 41 | 4. Receivers **MAY** ignore cancellation notifications if: 42 | - The referenced request is unknown 43 | - Processing has already completed 44 | - The request cannot be cancelled 45 | 5. The sender of the cancellation notification **SHOULD** ignore any response to the 46 | request that arrives afterward 47 | 48 | ## Timing Considerations 49 | 50 | Due to network latency, cancellation notifications may arrive after request processing 51 | has completed, and potentially after a response has already been sent. 52 | 53 | Both parties **MUST** handle these race conditions gracefully: 54 | 55 | ```mermaid 56 | sequenceDiagram 57 | participant Client 58 | participant Server 59 | 60 | Client->>Server: Request (ID: 123) 61 | Note over Server: Processing starts 62 | Client--)Server: notifications/cancelled (ID: 123) 63 | alt 64 | Note over Server: Processing may have
completed before
cancellation arrives 65 | else If not completed 66 | Note over Server: Stop processing 67 | end 68 | ``` 69 | 70 | ## Implementation Notes 71 | 72 | - Both parties **SHOULD** log cancellation reasons for debugging 73 | - Application UIs **SHOULD** indicate when cancellation is requested 74 | 75 | ## Error Handling 76 | 77 | Invalid cancellation notifications **SHOULD** be ignored: 78 | 79 | - Unknown request IDs 80 | - Already completed requests 81 | - Malformed notifications 82 | 83 | This maintains the "fire and forget" nature of notifications while allowing for race 84 | conditions in asynchronous communication. 85 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/basic/utilities/ping.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Ping 3 | weight: 5 4 | --- 5 | 6 | **Protocol Revision**: 2024-11-05 7 | 8 | The Model Context Protocol includes an optional ping mechanism that allows either party 9 | to verify that their counterpart is still responsive and the connection is alive. 10 | 11 | ## Overview 12 | 13 | The ping functionality is implemented through a simple request/response pattern. Either 14 | the client or server can initiate a ping by sending a `ping` request. 15 | 16 | ## Message Format 17 | 18 | A ping request is a standard JSON-RPC request with no parameters: 19 | 20 | ```json 21 | { 22 | "jsonrpc": "2.0", 23 | "id": "123", 24 | "method": "ping" 25 | } 26 | ``` 27 | 28 | ## Behavior Requirements 29 | 30 | 1. The receiver **MUST** respond promptly with an empty response: 31 | 32 | ```json 33 | { 34 | "jsonrpc": "2.0", 35 | "id": "123", 36 | "result": {} 37 | } 38 | ``` 39 | 40 | 2. If no response is received within a reasonable timeout period, the sender **MAY**: 41 | - Consider the connection stale 42 | - Terminate the connection 43 | - Attempt reconnection procedures 44 | 45 | ## Usage Patterns 46 | 47 | ```mermaid 48 | sequenceDiagram 49 | participant Sender 50 | participant Receiver 51 | 52 | Sender->>Receiver: ping request 53 | Receiver->>Sender: empty response 54 | ``` 55 | 56 | ## Implementation Considerations 57 | 58 | - Implementations **SHOULD** periodically issue pings to detect connection health 59 | - The frequency of pings **SHOULD** be configurable 60 | - Timeouts **SHOULD** be appropriate for the network environment 61 | - Excessive pinging **SHOULD** be avoided to reduce network overhead 62 | 63 | ## Error Handling 64 | 65 | - Timeouts **SHOULD** be treated as connection failures 66 | - Multiple failed pings **MAY** trigger connection reset 67 | - Implementations **SHOULD** log ping failures for diagnostics 68 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/basic/utilities/progress.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Progress 3 | weight: 30 4 | --- 5 | 6 | **Protocol Revision**: 2024-11-05 7 | 8 | The Model Context Protocol (MCP) supports optional progress tracking for long-running 9 | operations through notification messages. Either side can send progress notifications to 10 | provide updates about operation status. 11 | 12 | ## Progress Flow 13 | 14 | When a party wants to _receive_ progress updates for a request, it includes a 15 | `progressToken` in the request metadata. 16 | 17 | - Progress tokens **MUST** be a string or integer value 18 | - Progress tokens can be chosen by the sender using any means, but **MUST** be unique 19 | across all active requests. 20 | 21 | ```json 22 | { 23 | "jsonrpc": "2.0", 24 | "id": 1, 25 | "method": "some_method", 26 | "params": { 27 | "_meta": { 28 | "progressToken": "abc123" 29 | } 30 | } 31 | } 32 | ``` 33 | 34 | The receiver **MAY** then send progress notifications containing: 35 | 36 | - The original progress token 37 | - The current progress value so far 38 | - An optional "total" value 39 | 40 | ```json 41 | { 42 | "jsonrpc": "2.0", 43 | "method": "notifications/progress", 44 | "params": { 45 | "progressToken": "abc123", 46 | "progress": 50, 47 | "total": 100 48 | } 49 | } 50 | ``` 51 | 52 | - The `progress` value **MUST** increase with each notification, even if the total is 53 | unknown. 54 | - The `progress` and the `total` values **MAY** be floating point. 55 | 56 | ## Behavior Requirements 57 | 58 | 1. Progress notifications **MUST** only reference tokens that: 59 | 60 | - Were provided in an active request 61 | - Are associated with an in-progress operation 62 | 63 | 2. Receivers of progress requests **MAY**: 64 | - Choose not to send any progress notifications 65 | - Send notifications at whatever frequency they deem appropriate 66 | - Omit the total value if unknown 67 | 68 | ```mermaid 69 | sequenceDiagram 70 | participant Sender 71 | participant Receiver 72 | 73 | Note over Sender,Receiver: Request with progress token 74 | Sender->>Receiver: Method request with progressToken 75 | 76 | Note over Sender,Receiver: Progress updates 77 | loop Progress Updates 78 | Receiver-->>Sender: Progress notification (0.2/1.0) 79 | Receiver-->>Sender: Progress notification (0.6/1.0) 80 | Receiver-->>Sender: Progress notification (1.0/1.0) 81 | end 82 | 83 | Note over Sender,Receiver: Operation complete 84 | Receiver->>Sender: Method response 85 | ``` 86 | 87 | ## Implementation Notes 88 | 89 | - Senders and receivers **SHOULD** track active progress tokens 90 | - Both parties **SHOULD** implement rate limiting to prevent flooding 91 | - Progress notifications **MUST** stop after completion 92 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/client/roots.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Roots 3 | type: docs 4 | weight: 40 5 | --- 6 | 7 | **Protocol Revision**: 2024-11-05 8 | 9 | The Model Context Protocol (MCP) provides a standardized way for clients to expose 10 | filesystem "roots" to servers. Roots define the boundaries of where servers can operate 11 | within the filesystem, allowing them to understand which directories and files they have 12 | access to. Servers can request the list of roots from supporting clients and receive 13 | notifications when that list changes. 14 | 15 | ## User Interaction Model 16 | 17 | Roots in MCP are typically exposed through workspace or project configuration interfaces. 18 | 19 | For example, implementations could offer a workspace/project picker that allows users to 20 | select directories and files the server should have access to. This can be combined with 21 | automatic workspace detection from version control systems or project files. 22 | 23 | However, implementations are free to expose roots through any interface pattern that 24 | suits their needs—the protocol itself does not mandate any specific user 25 | interaction model. 26 | 27 | ## Capabilities 28 | 29 | Clients that support roots **MUST** declare the `roots` capability during 30 | [initialization](/specification/2024-11-05/basic/lifecycle#initialization): 31 | 32 | ```json 33 | { 34 | "capabilities": { 35 | "roots": { 36 | "listChanged": true 37 | } 38 | } 39 | } 40 | ``` 41 | 42 | `listChanged` indicates whether the client will emit notifications when the list of roots 43 | changes. 44 | 45 | ## Protocol Messages 46 | 47 | ### Listing Roots 48 | 49 | To retrieve roots, servers send a `roots/list` request: 50 | 51 | **Request:** 52 | 53 | ```json 54 | { 55 | "jsonrpc": "2.0", 56 | "id": 1, 57 | "method": "roots/list" 58 | } 59 | ``` 60 | 61 | **Response:** 62 | 63 | ```json 64 | { 65 | "jsonrpc": "2.0", 66 | "id": 1, 67 | "result": { 68 | "roots": [ 69 | { 70 | "uri": "file:///home/user/projects/myproject", 71 | "name": "My Project" 72 | } 73 | ] 74 | } 75 | } 76 | ``` 77 | 78 | ### Root List Changes 79 | 80 | When roots change, clients that support `listChanged` **MUST** send a notification: 81 | 82 | ```json 83 | { 84 | "jsonrpc": "2.0", 85 | "method": "notifications/roots/list_changed" 86 | } 87 | ``` 88 | 89 | ## Message Flow 90 | 91 | ```mermaid 92 | sequenceDiagram 93 | participant Server 94 | participant Client 95 | 96 | Note over Server,Client: Discovery 97 | Server->>Client: roots/list 98 | Client-->>Server: Available roots 99 | 100 | Note over Server,Client: Changes 101 | Client--)Server: notifications/roots/list_changed 102 | Server->>Client: roots/list 103 | Client-->>Server: Updated roots 104 | ``` 105 | 106 | ## Data Types 107 | 108 | ### Root 109 | 110 | A root definition includes: 111 | 112 | - `uri`: Unique identifier for the root. This **MUST** be a `file://` URI in the current 113 | specification. 114 | - `name`: Optional human-readable name for display purposes. 115 | 116 | Example roots for different use cases: 117 | 118 | #### Project Directory 119 | 120 | ```json 121 | { 122 | "uri": "file:///home/user/projects/myproject", 123 | "name": "My Project" 124 | } 125 | ``` 126 | 127 | #### Multiple Repositories 128 | 129 | ```json 130 | [ 131 | { 132 | "uri": "file:///home/user/repos/frontend", 133 | "name": "Frontend Repository" 134 | }, 135 | { 136 | "uri": "file:///home/user/repos/backend", 137 | "name": "Backend Repository" 138 | } 139 | ] 140 | ``` 141 | 142 | ## Error Handling 143 | 144 | Clients **SHOULD** return standard JSON-RPC errors for common failure cases: 145 | 146 | - Client does not support roots: `-32601` (Method not found) 147 | - Internal errors: `-32603` 148 | 149 | Example error: 150 | 151 | ```json 152 | { 153 | "jsonrpc": "2.0", 154 | "id": 1, 155 | "error": { 156 | "code": -32601, 157 | "message": "Roots not supported", 158 | "data": { 159 | "reason": "Client does not have roots capability" 160 | } 161 | } 162 | } 163 | ``` 164 | 165 | ## Security Considerations 166 | 167 | 1. Clients **MUST**: 168 | 169 | - Only expose roots with appropriate permissions 170 | - Validate all root URIs to prevent path traversal 171 | - Implement proper access controls 172 | - Monitor root accessibility 173 | 174 | 2. Servers **SHOULD**: 175 | - Handle cases where roots become unavailable 176 | - Respect root boundaries during operations 177 | - Validate all paths against provided roots 178 | 179 | ## Implementation Guidelines 180 | 181 | 1. Clients **SHOULD**: 182 | 183 | - Prompt users for consent before exposing roots to servers 184 | - Provide clear user interfaces for root management 185 | - Validate root accessibility before exposing 186 | - Monitor for root changes 187 | 188 | 2. Servers **SHOULD**: 189 | - Check for roots capability before usage 190 | - Handle root list changes gracefully 191 | - Respect root boundaries in operations 192 | - Cache root information appropriately 193 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/client/sampling.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Sampling 3 | type: docs 4 | weight: 40 5 | --- 6 | 7 | **Protocol Revision**: 2024-11-05 8 | 9 | The Model Context Protocol (MCP) provides a standardized way for servers to request LLM 10 | sampling ("completions" or "generations") from language models via clients. This flow 11 | allows clients to maintain control over model access, selection, and permissions while 12 | enabling servers to leverage AI capabilities—with no server API keys necessary. 13 | Servers can request text or image-based interactions and optionally include context from 14 | MCP servers in their prompts. 15 | 16 | ## User Interaction Model 17 | 18 | Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to 19 | occur _nested_ inside other MCP server features. 20 | 21 | Implementations are free to expose sampling through any interface pattern that suits 22 | their needs—the protocol itself does not mandate any specific user interaction 23 | model. 24 | 25 | 26 | For trust & safety and security, there **SHOULD** always 27 | be a human in the loop with the ability to deny sampling requests. 28 | 29 | Applications **SHOULD**: 30 | 31 | - Provide UI that makes it easy and intuitive to review sampling requests 32 | - Allow users to view and edit prompts before sending 33 | - Present generated responses for review before delivery 34 | 35 | 36 | ## Capabilities 37 | 38 | Clients that support sampling **MUST** declare the `sampling` capability during 39 | [initialization](/specification/2024-11-05/basic/lifecycle#initialization): 40 | 41 | ```json 42 | { 43 | "capabilities": { 44 | "sampling": {} 45 | } 46 | } 47 | ``` 48 | 49 | ## Protocol Messages 50 | 51 | ### Creating Messages 52 | 53 | To request a language model generation, servers send a `sampling/createMessage` request: 54 | 55 | **Request:** 56 | 57 | ```json 58 | { 59 | "jsonrpc": "2.0", 60 | "id": 1, 61 | "method": "sampling/createMessage", 62 | "params": { 63 | "messages": [ 64 | { 65 | "role": "user", 66 | "content": { 67 | "type": "text", 68 | "text": "What is the capital of France?" 69 | } 70 | } 71 | ], 72 | "modelPreferences": { 73 | "hints": [ 74 | { 75 | "name": "claude-3-sonnet" 76 | } 77 | ], 78 | "intelligencePriority": 0.8, 79 | "speedPriority": 0.5 80 | }, 81 | "systemPrompt": "You are a helpful assistant.", 82 | "maxTokens": 100 83 | } 84 | } 85 | ``` 86 | 87 | **Response:** 88 | 89 | ```json 90 | { 91 | "jsonrpc": "2.0", 92 | "id": 1, 93 | "result": { 94 | "role": "assistant", 95 | "content": { 96 | "type": "text", 97 | "text": "The capital of France is Paris." 98 | }, 99 | "model": "claude-3-sonnet-20240307", 100 | "stopReason": "endTurn" 101 | } 102 | } 103 | ``` 104 | 105 | ## Message Flow 106 | 107 | ```mermaid 108 | sequenceDiagram 109 | participant Server 110 | participant Client 111 | participant User 112 | participant LLM 113 | 114 | Note over Server,Client: Server initiates sampling 115 | Server->>Client: sampling/createMessage 116 | 117 | Note over Client,User: Human-in-the-loop review 118 | Client->>User: Present request for approval 119 | User-->>Client: Review and approve/modify 120 | 121 | Note over Client,LLM: Model interaction 122 | Client->>LLM: Forward approved request 123 | LLM-->>Client: Return generation 124 | 125 | Note over Client,User: Response review 126 | Client->>User: Present response for approval 127 | User-->>Client: Review and approve/modify 128 | 129 | Note over Server,Client: Complete request 130 | Client-->>Server: Return approved response 131 | ``` 132 | 133 | ## Data Types 134 | 135 | ### Messages 136 | 137 | Sampling messages can contain: 138 | 139 | #### Text Content 140 | 141 | ```json 142 | { 143 | "type": "text", 144 | "text": "The message content" 145 | } 146 | ``` 147 | 148 | #### Image Content 149 | 150 | ```json 151 | { 152 | "type": "image", 153 | "data": "base64-encoded-image-data", 154 | "mimeType": "image/jpeg" 155 | } 156 | ``` 157 | 158 | ### Model Preferences 159 | 160 | Model selection in MCP requires careful abstraction since servers and clients may use 161 | different AI providers with distinct model offerings. A server cannot simply request a 162 | specific model by name since the client may not have access to that exact model or may 163 | prefer to use a different provider's equivalent model. 164 | 165 | To solve this, MCP implements a preference system that combines abstract capability 166 | priorities with optional model hints: 167 | 168 | #### Capability Priorities 169 | 170 | Servers express their needs through three normalized priority values (0-1): 171 | 172 | - `costPriority`: How important is minimizing costs? Higher values prefer cheaper models. 173 | - `speedPriority`: How important is low latency? Higher values prefer faster models. 174 | - `intelligencePriority`: How important are advanced capabilities? Higher values prefer 175 | more capable models. 176 | 177 | #### Model Hints 178 | 179 | While priorities help select models based on characteristics, `hints` allow servers to 180 | suggest specific models or model families: 181 | 182 | - Hints are treated as substrings that can match model names flexibly 183 | - Multiple hints are evaluated in order of preference 184 | - Clients **MAY** map hints to equivalent models from different providers 185 | - Hints are advisory—clients make final model selection 186 | 187 | For example: 188 | 189 | ```json 190 | { 191 | "hints": [ 192 | { "name": "claude-3-sonnet" }, // Prefer Sonnet-class models 193 | { "name": "claude" } // Fall back to any Claude model 194 | ], 195 | "costPriority": 0.3, // Cost is less important 196 | "speedPriority": 0.8, // Speed is very important 197 | "intelligencePriority": 0.5 // Moderate capability needs 198 | } 199 | ``` 200 | 201 | The client processes these preferences to select an appropriate model from its available 202 | options. For instance, if the client doesn't have access to Claude models but has Gemini, 203 | it might map the sonnet hint to `gemini-1.5-pro` based on similar capabilities. 204 | 205 | ## Error Handling 206 | 207 | Clients **SHOULD** return errors for common failure cases: 208 | 209 | Example error: 210 | 211 | ```json 212 | { 213 | "jsonrpc": "2.0", 214 | "id": 1, 215 | "error": { 216 | "code": -1, 217 | "message": "User rejected sampling request" 218 | } 219 | } 220 | ``` 221 | 222 | ## Security Considerations 223 | 224 | 1. Clients **SHOULD** implement user approval controls 225 | 2. Both parties **SHOULD** validate message content 226 | 3. Clients **SHOULD** respect model preference hints 227 | 4. Clients **SHOULD** implement rate limiting 228 | 5. Both parties **MUST** handle sensitive data appropriately 229 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Specification 3 | --- 4 | 5 | [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that 6 | enables seamless integration between LLM applications and external data sources and 7 | tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating 8 | custom AI workflows, MCP provides a standardized way to connect LLMs with the context 9 | they need. 10 | 11 | This specification defines the authoritative protocol requirements, based on the 12 | TypeScript schema in 13 | [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/2024-11-05/schema.ts). 14 | 15 | For implementation guides and examples, visit 16 | [modelcontextprotocol.io](https://modelcontextprotocol.io). 17 | 18 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 19 | NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 20 | interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) 21 | [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)] 22 | [[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)] when, and only when, they 23 | appear in all capitals, as shown here. 24 | 25 | ## Overview 26 | 27 | MCP provides a standardized way for applications to: 28 | 29 | - Share contextual information with language models 30 | - Expose tools and capabilities to AI systems 31 | - Build composable integrations and workflows 32 | 33 | The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish 34 | communication between: 35 | 36 | - **Hosts**: LLM applications that initiate connections 37 | - **Clients**: Connectors within the host application 38 | - **Servers**: Services that provide context and capabilities 39 | 40 | MCP takes some inspiration from the 41 | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which 42 | standardizes how to add support for programming languages across a whole ecosystem of 43 | development tools. In a similar way, MCP standardizes how to integrate additional context 44 | and tools into the ecosystem of AI applications. 45 | 46 | ## Key Details 47 | 48 | ### Base Protocol 49 | 50 | - [JSON-RPC](https://www.jsonrpc.org/) message format 51 | - Stateful connections 52 | - Server and client capability negotiation 53 | 54 | ### Features 55 | 56 | Servers offer any of the following features to clients: 57 | 58 | - **Resources**: Context and data, for the user or the AI model to use 59 | - **Prompts**: Templated messages and workflows for users 60 | - **Tools**: Functions for the AI model to execute 61 | 62 | Clients may offer the following feature to servers: 63 | 64 | - **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions 65 | 66 | ### Additional Utilities 67 | 68 | - Configuration 69 | - Progress tracking 70 | - Cancellation 71 | - Error reporting 72 | - Logging 73 | 74 | ## Security and Trust & Safety 75 | 76 | The Model Context Protocol enables powerful capabilities through arbitrary data access 77 | and code execution paths. With this power comes important security and trust 78 | considerations that all implementors must carefully address. 79 | 80 | ### Key Principles 81 | 82 | 1. **User Consent and Control** 83 | 84 | - Users must explicitly consent to and understand all data access and operations 85 | - Users must retain control over what data is shared and what actions are taken 86 | - Implementors should provide clear UIs for reviewing and authorizing activities 87 | 88 | 2. **Data Privacy** 89 | 90 | - Hosts must obtain explicit user consent before exposing user data to servers 91 | - Hosts must not transmit resource data elsewhere without user consent 92 | - User data should be protected with appropriate access controls 93 | 94 | 3. **Tool Safety** 95 | 96 | - Tools represent arbitrary code execution and must be treated with appropriate 97 | caution 98 | - Hosts must obtain explicit user consent before invoking any tool 99 | - Users should understand what each tool does before authorizing its use 100 | 101 | 4. **LLM Sampling Controls** 102 | - Users must explicitly approve any LLM sampling requests 103 | - Users should control: 104 | - Whether sampling occurs at all 105 | - The actual prompt that will be sent 106 | - What results the server can see 107 | - The protocol intentionally limits server visibility into prompts 108 | 109 | ### Implementation Guidelines 110 | 111 | While MCP itself cannot enforce these security principles at the protocol level, 112 | implementors **SHOULD**: 113 | 114 | 1. Build robust consent and authorization flows into their applications 115 | 2. Provide clear documentation of security implications 116 | 3. Implement appropriate access controls and data protections 117 | 4. Follow security best practices in their integrations 118 | 5. Consider privacy implications in their feature designs 119 | 120 | ## Learn More 121 | 122 | Explore the detailed specification for each protocol component: 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/server/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overview 3 | --- 4 | 5 | **Protocol Revision**: 2024-11-05 6 | 7 | Servers provide the fundamental building blocks for adding context to language models via 8 | MCP. These primitives enable rich interactions between clients, servers, and language 9 | models: 10 | 11 | - **Prompts**: Pre-defined templates or instructions that guide language model 12 | interactions 13 | - **Resources**: Structured data or content that provides additional context to the model 14 | - **Tools**: Executable functions that allow models to perform actions or retrieve 15 | information 16 | 17 | Each primitive can be summarized in the following control hierarchy: 18 | 19 | | Primitive | Control | Description | Example | 20 | | --------- | ---------------------- | -------------------------------------------------- | ------------------------------- | 21 | | Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options | 22 | | Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history | 23 | | Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing | 24 | 25 | Explore these key primitives in more detail below: 26 | 27 | 28 | 29 | 30 | 31 | 32 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/server/resource-picker.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/specification/2024-11-05/server/resource-picker.png -------------------------------------------------------------------------------- /docs/specification/2024-11-05/server/slash-command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/specification/2024-11-05/server/slash-command.png -------------------------------------------------------------------------------- /docs/specification/2024-11-05/server/utilities/completion.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Completion 3 | --- 4 | 5 | **Protocol Revision**: 2024-11-05 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to offer 8 | argument autocompletion suggestions for prompts and resource URIs. This enables rich, 9 | IDE-like experiences where users receive contextual suggestions while entering argument 10 | values. 11 | 12 | ## User Interaction Model 13 | 14 | Completion in MCP is designed to support interactive user experiences similar to IDE code 15 | completion. 16 | 17 | For example, applications may show completion suggestions in a dropdown or popup menu as 18 | users type, with the ability to filter and select from available options. 19 | 20 | However, implementations are free to expose completion through any interface pattern that 21 | suits their needs—the protocol itself does not mandate any specific user 22 | interaction model. 23 | 24 | ## Protocol Messages 25 | 26 | ### Requesting Completions 27 | 28 | To get completion suggestions, clients send a `completion/complete` request specifying 29 | what is being completed through a reference type: 30 | 31 | **Request:** 32 | 33 | ```json 34 | { 35 | "jsonrpc": "2.0", 36 | "id": 1, 37 | "method": "completion/complete", 38 | "params": { 39 | "ref": { 40 | "type": "ref/prompt", 41 | "name": "code_review" 42 | }, 43 | "argument": { 44 | "name": "language", 45 | "value": "py" 46 | } 47 | } 48 | } 49 | ``` 50 | 51 | **Response:** 52 | 53 | ```json 54 | { 55 | "jsonrpc": "2.0", 56 | "id": 1, 57 | "result": { 58 | "completion": { 59 | "values": ["python", "pytorch", "pyside"], 60 | "total": 10, 61 | "hasMore": true 62 | } 63 | } 64 | } 65 | ``` 66 | 67 | ### Reference Types 68 | 69 | The protocol supports two types of completion references: 70 | 71 | | Type | Description | Example | 72 | | -------------- | --------------------------- | --------------------------------------------------- | 73 | | `ref/prompt` | References a prompt by name | `{"type": "ref/prompt", "name": "code_review"}` | 74 | | `ref/resource` | References a resource URI | `{"type": "ref/resource", "uri": "file:///{path}"}` | 75 | 76 | ### Completion Results 77 | 78 | Servers return an array of completion values ranked by relevance, with: 79 | 80 | - Maximum 100 items per response 81 | - Optional total number of available matches 82 | - Boolean indicating if additional results exist 83 | 84 | ## Message Flow 85 | 86 | ```mermaid 87 | sequenceDiagram 88 | participant Client 89 | participant Server 90 | 91 | Note over Client: User types argument 92 | Client->>Server: completion/complete 93 | Server-->>Client: Completion suggestions 94 | 95 | Note over Client: User continues typing 96 | Client->>Server: completion/complete 97 | Server-->>Client: Refined suggestions 98 | ``` 99 | 100 | ## Data Types 101 | 102 | ### CompleteRequest 103 | 104 | - `ref`: A `PromptReference` or `ResourceReference` 105 | - `argument`: Object containing: 106 | - `name`: Argument name 107 | - `value`: Current value 108 | 109 | ### CompleteResult 110 | 111 | - `completion`: Object containing: 112 | - `values`: Array of suggestions (max 100) 113 | - `total`: Optional total matches 114 | - `hasMore`: Additional results flag 115 | 116 | ## Implementation Considerations 117 | 118 | 1. Servers **SHOULD**: 119 | 120 | - Return suggestions sorted by relevance 121 | - Implement fuzzy matching where appropriate 122 | - Rate limit completion requests 123 | - Validate all inputs 124 | 125 | 2. Clients **SHOULD**: 126 | - Debounce rapid completion requests 127 | - Cache completion results where appropriate 128 | - Handle missing or partial results gracefully 129 | 130 | ## Security 131 | 132 | Implementations **MUST**: 133 | 134 | - Validate all completion inputs 135 | - Implement appropriate rate limiting 136 | - Control access to sensitive suggestions 137 | - Prevent completion-based information disclosure 138 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/server/utilities/logging.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Logging 3 | --- 4 | 5 | **Protocol Revision**: 2024-11-05 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to send 8 | structured log messages to clients. Clients can control logging verbosity by setting 9 | minimum log levels, with servers sending notifications containing severity levels, 10 | optional logger names, and arbitrary JSON-serializable data. 11 | 12 | ## User Interaction Model 13 | 14 | Implementations are free to expose logging through any interface pattern that suits their 15 | needs—the protocol itself does not mandate any specific user interaction model. 16 | 17 | ## Capabilities 18 | 19 | Servers that emit log message notifications **MUST** declare the `logging` capability: 20 | 21 | ```json 22 | { 23 | "capabilities": { 24 | "logging": {} 25 | } 26 | } 27 | ``` 28 | 29 | ## Log Levels 30 | 31 | The protocol follows the standard syslog severity levels specified in 32 | [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1): 33 | 34 | | Level | Description | Example Use Case | 35 | | --------- | -------------------------------- | -------------------------- | 36 | | debug | Detailed debugging information | Function entry/exit points | 37 | | info | General informational messages | Operation progress updates | 38 | | notice | Normal but significant events | Configuration changes | 39 | | warning | Warning conditions | Deprecated feature usage | 40 | | error | Error conditions | Operation failures | 41 | | critical | Critical conditions | System component failures | 42 | | alert | Action must be taken immediately | Data corruption detected | 43 | | emergency | System is unusable | Complete system failure | 44 | 45 | ## Protocol Messages 46 | 47 | ### Setting Log Level 48 | 49 | To configure the minimum log level, clients **MAY** send a `logging/setLevel` request: 50 | 51 | **Request:** 52 | 53 | ```json 54 | { 55 | "jsonrpc": "2.0", 56 | "id": 1, 57 | "method": "logging/setLevel", 58 | "params": { 59 | "level": "info" 60 | } 61 | } 62 | ``` 63 | 64 | ### Log Message Notifications 65 | 66 | Servers send log messages using `notifications/message` notifications: 67 | 68 | ```json 69 | { 70 | "jsonrpc": "2.0", 71 | "method": "notifications/message", 72 | "params": { 73 | "level": "error", 74 | "logger": "database", 75 | "data": { 76 | "error": "Connection failed", 77 | "details": { 78 | "host": "localhost", 79 | "port": 5432 80 | } 81 | } 82 | } 83 | } 84 | ``` 85 | 86 | ## Message Flow 87 | 88 | ```mermaid 89 | sequenceDiagram 90 | participant Client 91 | participant Server 92 | 93 | Note over Client,Server: Configure Logging 94 | Client->>Server: logging/setLevel (info) 95 | Server-->>Client: Empty Result 96 | 97 | Note over Client,Server: Server Activity 98 | Server--)Client: notifications/message (info) 99 | Server--)Client: notifications/message (warning) 100 | Server--)Client: notifications/message (error) 101 | 102 | Note over Client,Server: Level Change 103 | Client->>Server: logging/setLevel (error) 104 | Server-->>Client: Empty Result 105 | Note over Server: Only sends error level
and above 106 | ``` 107 | 108 | ## Error Handling 109 | 110 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases: 111 | 112 | - Invalid log level: `-32602` (Invalid params) 113 | - Configuration errors: `-32603` (Internal error) 114 | 115 | ## Implementation Considerations 116 | 117 | 1. Servers **SHOULD**: 118 | 119 | - Rate limit log messages 120 | - Include relevant context in data field 121 | - Use consistent logger names 122 | - Remove sensitive information 123 | 124 | 2. Clients **MAY**: 125 | - Present log messages in the UI 126 | - Implement log filtering/search 127 | - Display severity visually 128 | - Persist log messages 129 | 130 | ## Security 131 | 132 | 1. Log messages **MUST NOT** contain: 133 | 134 | - Credentials or secrets 135 | - Personal identifying information 136 | - Internal system details that could aid attacks 137 | 138 | 2. Implementations **SHOULD**: 139 | - Rate limit messages 140 | - Validate all data fields 141 | - Control log access 142 | - Monitor for sensitive content 143 | -------------------------------------------------------------------------------- /docs/specification/2024-11-05/server/utilities/pagination.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Pagination 3 | --- 4 | 5 | **Protocol Revision**: 2024-11-05 6 | 7 | The Model Context Protocol (MCP) supports paginating list operations that may return 8 | large result sets. Pagination allows servers to yield results in smaller chunks rather 9 | than all at once. 10 | 11 | Pagination is especially important when connecting to external services over the 12 | internet, but also useful for local integrations to avoid performance issues with large 13 | data sets. 14 | 15 | ## Pagination Model 16 | 17 | Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages. 18 | 19 | - The **cursor** is an opaque string token, representing a position in the result set 20 | - **Page size** is determined by the server, and clients **MUST NOT** assume a fixed page 21 | size 22 | 23 | ## Response Format 24 | 25 | Pagination starts when the server sends a **response** that includes: 26 | 27 | - The current page of results 28 | - An optional `nextCursor` field if more results exist 29 | 30 | ```json 31 | { 32 | "jsonrpc": "2.0", 33 | "id": "123", 34 | "result": { 35 | "resources": [...], 36 | "nextCursor": "eyJwYWdlIjogM30=" 37 | } 38 | } 39 | ``` 40 | 41 | ## Request Format 42 | 43 | After receiving a cursor, the client can _continue_ paginating by issuing a request 44 | including that cursor: 45 | 46 | ```json 47 | { 48 | "jsonrpc": "2.0", 49 | "method": "resources/list", 50 | "params": { 51 | "cursor": "eyJwYWdlIjogMn0=" 52 | } 53 | } 54 | ``` 55 | 56 | ## Pagination Flow 57 | 58 | ```mermaid 59 | sequenceDiagram 60 | participant Client 61 | participant Server 62 | 63 | Client->>Server: List Request (no cursor) 64 | loop Pagination Loop 65 | Server-->>Client: Page of results + nextCursor 66 | Client->>Server: List Request (with cursor) 67 | end 68 | ``` 69 | 70 | ## Operations Supporting Pagination 71 | 72 | The following MCP operations support pagination: 73 | 74 | - `resources/list` - List available resources 75 | - `resources/templates/list` - List resource templates 76 | - `prompts/list` - List available prompts 77 | - `tools/list` - List available tools 78 | 79 | ## Implementation Guidelines 80 | 81 | 1. Servers **SHOULD**: 82 | 83 | - Provide stable cursors 84 | - Handle invalid cursors gracefully 85 | 86 | 2. Clients **SHOULD**: 87 | 88 | - Treat a missing `nextCursor` as the end of results 89 | - Support both paginated and non-paginated flows 90 | 91 | 3. Clients **MUST** treat cursors as opaque tokens: 92 | - Don't make assumptions about cursor format 93 | - Don't attempt to parse or modify cursors 94 | - Don't persist cursors across sessions 95 | 96 | ## Error Handling 97 | 98 | Invalid cursors **SHOULD** result in an error with code -32602 (Invalid params). 99 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/architecture/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Architecture 3 | --- 4 | 5 | The Model Context Protocol (MCP) follows a client-host-server architecture where each 6 | host can run multiple client instances. This architecture enables users to integrate AI 7 | capabilities across applications while maintaining clear security boundaries and 8 | isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused 9 | on context exchange and sampling coordination between clients and servers. 10 | 11 | ## Core Components 12 | 13 | ```mermaid 14 | graph LR 15 | subgraph "Application Host Process" 16 | H[Host] 17 | C1[Client 1] 18 | C2[Client 2] 19 | C3[Client 3] 20 | H --> C1 21 | H --> C2 22 | H --> C3 23 | end 24 | 25 | subgraph "Local machine" 26 | S1[Server 1
Files & Git] 27 | S2[Server 2
Database] 28 | R1[("Local
Resource A")] 29 | R2[("Local
Resource B")] 30 | 31 | C1 --> S1 32 | C2 --> S2 33 | S1 <--> R1 34 | S2 <--> R2 35 | end 36 | 37 | subgraph "Internet" 38 | S3[Server 3
External APIs] 39 | R3[("Remote
Resource C")] 40 | 41 | C3 --> S3 42 | S3 <--> R3 43 | end 44 | ``` 45 | 46 | ### Host 47 | 48 | The host process acts as the container and coordinator: 49 | 50 | - Creates and manages multiple client instances 51 | - Controls client connection permissions and lifecycle 52 | - Enforces security policies and consent requirements 53 | - Handles user authorization decisions 54 | - Coordinates AI/LLM integration and sampling 55 | - Manages context aggregation across clients 56 | 57 | ### Clients 58 | 59 | Each client is created by the host and maintains an isolated server connection: 60 | 61 | - Establishes one stateful session per server 62 | - Handles protocol negotiation and capability exchange 63 | - Routes protocol messages bidirectionally 64 | - Manages subscriptions and notifications 65 | - Maintains security boundaries between servers 66 | 67 | A host application creates and manages multiple clients, with each client having a 1:1 68 | relationship with a particular server. 69 | 70 | ### Servers 71 | 72 | Servers provide specialized context and capabilities: 73 | 74 | - Expose resources, tools and prompts via MCP primitives 75 | - Operate independently with focused responsibilities 76 | - Request sampling through client interfaces 77 | - Must respect security constraints 78 | - Can be local processes or remote services 79 | 80 | ## Design Principles 81 | 82 | MCP is built on several key design principles that inform its architecture and 83 | implementation: 84 | 85 | 1. **Servers should be extremely easy to build** 86 | 87 | - Host applications handle complex orchestration responsibilities 88 | - Servers focus on specific, well-defined capabilities 89 | - Simple interfaces minimize implementation overhead 90 | - Clear separation enables maintainable code 91 | 92 | 2. **Servers should be highly composable** 93 | 94 | - Each server provides focused functionality in isolation 95 | - Multiple servers can be combined seamlessly 96 | - Shared protocol enables interoperability 97 | - Modular design supports extensibility 98 | 99 | 3. **Servers should not be able to read the whole conversation, nor "see into" other 100 | servers** 101 | 102 | - Servers receive only necessary contextual information 103 | - Full conversation history stays with the host 104 | - Each server connection maintains isolation 105 | - Cross-server interactions are controlled by the host 106 | - Host process enforces security boundaries 107 | 108 | 4. **Features can be added to servers and clients progressively** 109 | - Core protocol provides minimal required functionality 110 | - Additional capabilities can be negotiated as needed 111 | - Servers and clients evolve independently 112 | - Protocol designed for future extensibility 113 | - Backwards compatibility is maintained 114 | 115 | ## Capability Negotiation 116 | 117 | The Model Context Protocol uses a capability-based negotiation system where clients and 118 | servers explicitly declare their supported features during initialization. Capabilities 119 | determine which protocol features and primitives are available during a session. 120 | 121 | - Servers declare capabilities like resource subscriptions, tool support, and prompt 122 | templates 123 | - Clients declare capabilities like sampling support and notification handling 124 | - Both parties must respect declared capabilities throughout the session 125 | - Additional capabilities can be negotiated through extensions to the protocol 126 | 127 | ```mermaid 128 | sequenceDiagram 129 | participant Host 130 | participant Client 131 | participant Server 132 | 133 | Host->>+Client: Initialize client 134 | Client->>+Server: Initialize session with capabilities 135 | Server-->>Client: Respond with supported capabilities 136 | 137 | Note over Host,Server: Active Session with Negotiated Features 138 | 139 | loop Client Requests 140 | Host->>Client: User- or model-initiated action 141 | Client->>Server: Request (tools/resources) 142 | Server-->>Client: Response 143 | Client-->>Host: Update UI or respond to model 144 | end 145 | 146 | loop Server Requests 147 | Server->>Client: Request (sampling) 148 | Client->>Host: Forward to AI 149 | Host-->>Client: AI response 150 | Client-->>Server: Response 151 | end 152 | 153 | loop Notifications 154 | Server--)Client: Resource updates 155 | Client--)Server: Status changes 156 | end 157 | 158 | Host->>Client: Terminate 159 | Client->>-Server: End session 160 | deactivate Server 161 | ``` 162 | 163 | Each capability unlocks specific protocol features for use during the session. For 164 | example: 165 | 166 | - Implemented [server features](/specification/2025-03-26/server) must be advertised in the 167 | server's capabilities 168 | - Emitting resource subscription notifications requires the server to declare 169 | subscription support 170 | - Tool invocation requires the server to declare tool capabilities 171 | - [Sampling](/specification/2025-03-26/client) requires the client to declare support in its 172 | capabilities 173 | 174 | This capability negotiation ensures clients and servers have a clear understanding of 175 | supported functionality while maintaining protocol extensibility. 176 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/basic/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overview 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | The Model Context Protocol consists of several key components that work together: 8 | 9 | - **Base Protocol**: Core JSON-RPC message types 10 | - **Lifecycle Management**: Connection initialization, capability negotiation, and 11 | session control 12 | - **Server Features**: Resources, prompts, and tools exposed by servers 13 | - **Client Features**: Sampling and root directory lists provided by clients 14 | - **Utilities**: Cross-cutting concerns like logging and argument completion 15 | 16 | All implementations **MUST** support the base protocol and lifecycle management 17 | components. Other components **MAY** be implemented based on the specific needs of the 18 | application. 19 | 20 | These protocol layers establish clear separation of concerns while enabling rich 21 | interactions between clients and servers. The modular design allows implementations to 22 | support exactly the features they need. 23 | 24 | ## Messages 25 | 26 | All messages between MCP clients and servers **MUST** follow the 27 | [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines 28 | these types of messages: 29 | 30 | ### Requests 31 | 32 | Requests are sent from the client to the server or vice versa, to initiate an operation. 33 | 34 | ```typescript 35 | { 36 | jsonrpc: "2.0"; 37 | id: string | number; 38 | method: string; 39 | params?: { 40 | [key: string]: unknown; 41 | }; 42 | } 43 | ``` 44 | 45 | - Requests **MUST** include a string or integer ID. 46 | - Unlike base JSON-RPC, the ID **MUST NOT** be `null`. 47 | - The request ID **MUST NOT** have been previously used by the requestor within the same 48 | session. 49 | 50 | ### Responses 51 | 52 | Responses are sent in reply to requests, containing the result or error of the operation. 53 | 54 | ```typescript 55 | { 56 | jsonrpc: "2.0"; 57 | id: string | number; 58 | result?: { 59 | [key: string]: unknown; 60 | } 61 | error?: { 62 | code: number; 63 | message: string; 64 | data?: unknown; 65 | } 66 | } 67 | ``` 68 | 69 | - Responses **MUST** include the same ID as the request they correspond to. 70 | - **Responses** are further sub-categorized as either **successful results** or 71 | **errors**. Either a `result` or an `error` **MUST** be set. A response **MUST NOT** 72 | set both. 73 | - Results **MAY** follow any JSON object structure, while errors **MUST** include an 74 | error code and message at minimum. 75 | - Error codes **MUST** be integers. 76 | 77 | ### Notifications 78 | 79 | Notifications are sent from the client to the server or vice versa, as a one-way message. 80 | The receiver **MUST NOT** send a response. 81 | 82 | ```typescript 83 | { 84 | jsonrpc: "2.0"; 85 | method: string; 86 | params?: { 87 | [key: string]: unknown; 88 | }; 89 | } 90 | ``` 91 | 92 | - Notifications **MUST NOT** include an ID. 93 | 94 | ### Batching 95 | 96 | JSON-RPC also defines a means to 97 | [batch multiple requests and notifications](https://www.jsonrpc.org/specification#batch), 98 | by sending them in an array. MCP implementations **MAY** support sending JSON-RPC 99 | batches, but **MUST** support receiving JSON-RPC batches. 100 | 101 | ## Auth 102 | 103 | MCP provides an [Authorization](/specification/2025-03-26/basic/authorization) framework for use with HTTP. 104 | Implementations using an HTTP-based transport **SHOULD** conform to this specification, 105 | whereas implementations using STDIO transport **SHOULD NOT** follow this specification, 106 | and instead retrieve credentials from the environment. 107 | 108 | Additionally, clients and servers **MAY** negotiate their own custom authentication and 109 | authorization strategies. 110 | 111 | For further discussions and contributions to the evolution of MCP’s auth mechanisms, join 112 | us in 113 | [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions) 114 | to help shape the future of the protocol! 115 | 116 | ## Schema 117 | 118 | The full specification of the protocol is defined as a 119 | [TypeScript schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-03-26/schema.ts). 120 | This is the source of truth for all protocol messages and structures. 121 | 122 | There is also a 123 | [JSON Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-03-26/schema.json), 124 | which is automatically generated from the TypeScript source of truth, for use with 125 | various automated tooling. 126 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/basic/utilities/cancellation.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Cancellation 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | The Model Context Protocol (MCP) supports optional cancellation of in-progress requests 8 | through notification messages. Either side can send a cancellation notification to 9 | indicate that a previously-issued request should be terminated. 10 | 11 | ## Cancellation Flow 12 | 13 | When a party wants to cancel an in-progress request, it sends a `notifications/cancelled` 14 | notification containing: 15 | 16 | - The ID of the request to cancel 17 | - An optional reason string that can be logged or displayed 18 | 19 | ```json 20 | { 21 | "jsonrpc": "2.0", 22 | "method": "notifications/cancelled", 23 | "params": { 24 | "requestId": "123", 25 | "reason": "User requested cancellation" 26 | } 27 | } 28 | ``` 29 | 30 | ## Behavior Requirements 31 | 32 | 1. Cancellation notifications **MUST** only reference requests that: 33 | - Were previously issued in the same direction 34 | - Are believed to still be in-progress 35 | 2. The `initialize` request **MUST NOT** be cancelled by clients 36 | 3. Receivers of cancellation notifications **SHOULD**: 37 | - Stop processing the cancelled request 38 | - Free associated resources 39 | - Not send a response for the cancelled request 40 | 4. Receivers **MAY** ignore cancellation notifications if: 41 | - The referenced request is unknown 42 | - Processing has already completed 43 | - The request cannot be cancelled 44 | 5. The sender of the cancellation notification **SHOULD** ignore any response to the 45 | request that arrives afterward 46 | 47 | ## Timing Considerations 48 | 49 | Due to network latency, cancellation notifications may arrive after request processing 50 | has completed, and potentially after a response has already been sent. 51 | 52 | Both parties **MUST** handle these race conditions gracefully: 53 | 54 | ```mermaid 55 | sequenceDiagram 56 | participant Client 57 | participant Server 58 | 59 | Client->>Server: Request (ID: 123) 60 | Note over Server: Processing starts 61 | Client--)Server: notifications/cancelled (ID: 123) 62 | alt 63 | Note over Server: Processing may have
completed before
cancellation arrives 64 | else If not completed 65 | Note over Server: Stop processing 66 | end 67 | ``` 68 | 69 | ## Implementation Notes 70 | 71 | - Both parties **SHOULD** log cancellation reasons for debugging 72 | - Application UIs **SHOULD** indicate when cancellation is requested 73 | 74 | ## Error Handling 75 | 76 | Invalid cancellation notifications **SHOULD** be ignored: 77 | 78 | - Unknown request IDs 79 | - Already completed requests 80 | - Malformed notifications 81 | 82 | This maintains the "fire and forget" nature of notifications while allowing for race 83 | conditions in asynchronous communication. 84 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/basic/utilities/ping.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Ping 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | The Model Context Protocol includes an optional ping mechanism that allows either party 8 | to verify that their counterpart is still responsive and the connection is alive. 9 | 10 | ## Overview 11 | 12 | The ping functionality is implemented through a simple request/response pattern. Either 13 | the client or server can initiate a ping by sending a `ping` request. 14 | 15 | ## Message Format 16 | 17 | A ping request is a standard JSON-RPC request with no parameters: 18 | 19 | ```json 20 | { 21 | "jsonrpc": "2.0", 22 | "id": "123", 23 | "method": "ping" 24 | } 25 | ``` 26 | 27 | ## Behavior Requirements 28 | 29 | 1. The receiver **MUST** respond promptly with an empty response: 30 | 31 | ```json 32 | { 33 | "jsonrpc": "2.0", 34 | "id": "123", 35 | "result": {} 36 | } 37 | ``` 38 | 39 | 2. If no response is received within a reasonable timeout period, the sender **MAY**: 40 | - Consider the connection stale 41 | - Terminate the connection 42 | - Attempt reconnection procedures 43 | 44 | ## Usage Patterns 45 | 46 | ```mermaid 47 | sequenceDiagram 48 | participant Sender 49 | participant Receiver 50 | 51 | Sender->>Receiver: ping request 52 | Receiver->>Sender: empty response 53 | ``` 54 | 55 | ## Implementation Considerations 56 | 57 | - Implementations **SHOULD** periodically issue pings to detect connection health 58 | - The frequency of pings **SHOULD** be configurable 59 | - Timeouts **SHOULD** be appropriate for the network environment 60 | - Excessive pinging **SHOULD** be avoided to reduce network overhead 61 | 62 | ## Error Handling 63 | 64 | - Timeouts **SHOULD** be treated as connection failures 65 | - Multiple failed pings **MAY** trigger connection reset 66 | - Implementations **SHOULD** log ping failures for diagnostics 67 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/basic/utilities/progress.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Progress 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | The Model Context Protocol (MCP) supports optional progress tracking for long-running 8 | operations through notification messages. Either side can send progress notifications to 9 | provide updates about operation status. 10 | 11 | ## Progress Flow 12 | 13 | When a party wants to _receive_ progress updates for a request, it includes a 14 | `progressToken` in the request metadata. 15 | 16 | - Progress tokens **MUST** be a string or integer value 17 | - Progress tokens can be chosen by the sender using any means, but **MUST** be unique 18 | across all active requests. 19 | 20 | ```json 21 | { 22 | "jsonrpc": "2.0", 23 | "id": 1, 24 | "method": "some_method", 25 | "params": { 26 | "_meta": { 27 | "progressToken": "abc123" 28 | } 29 | } 30 | } 31 | ``` 32 | 33 | The receiver **MAY** then send progress notifications containing: 34 | 35 | - The original progress token 36 | - The current progress value so far 37 | - An optional "total" value 38 | - An optional "message" value 39 | 40 | ```json 41 | { 42 | "jsonrpc": "2.0", 43 | "method": "notifications/progress", 44 | "params": { 45 | "progressToken": "abc123", 46 | "progress": 50, 47 | "total": 100, 48 | "message": "Reticulating splines..." 49 | } 50 | } 51 | ``` 52 | 53 | - The `progress` value **MUST** increase with each notification, even if the total is 54 | unknown. 55 | - The `progress` and the `total` values **MAY** be floating point. 56 | - The `message` field **SHOULD** provide relevant human readable progress information. 57 | 58 | ## Behavior Requirements 59 | 60 | 1. Progress notifications **MUST** only reference tokens that: 61 | 62 | - Were provided in an active request 63 | - Are associated with an in-progress operation 64 | 65 | 2. Receivers of progress requests **MAY**: 66 | - Choose not to send any progress notifications 67 | - Send notifications at whatever frequency they deem appropriate 68 | - Omit the total value if unknown 69 | 70 | ```mermaid 71 | sequenceDiagram 72 | participant Sender 73 | participant Receiver 74 | 75 | Note over Sender,Receiver: Request with progress token 76 | Sender->>Receiver: Method request with progressToken 77 | 78 | Note over Sender,Receiver: Progress updates 79 | loop Progress Updates 80 | Receiver-->>Sender: Progress notification (0.2/1.0) 81 | Receiver-->>Sender: Progress notification (0.6/1.0) 82 | Receiver-->>Sender: Progress notification (1.0/1.0) 83 | end 84 | 85 | Note over Sender,Receiver: Operation complete 86 | Receiver->>Sender: Method response 87 | ``` 88 | 89 | ## Implementation Notes 90 | 91 | - Senders and receivers **SHOULD** track active progress tokens 92 | - Both parties **SHOULD** implement rate limiting to prevent flooding 93 | - Progress notifications **MUST** stop after completion 94 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/changelog.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Key Changes 3 | --- 4 | 5 | This document lists changes made to the Model Context Protocol (MCP) specification since 6 | the previous revision, [2024-11-05](/specification/2024-11-05). 7 | 8 | ## Major changes 9 | 10 | 1. Added a comprehensive **[authorization framework](/specification/2025-03-26/basic/authorization)** 11 | based on OAuth 2.1 (PR 12 | [#133](https://github.com/modelcontextprotocol/specification/pull/133)) 13 | 1. Replaced the previous HTTP+SSE transport with a more flexible **[Streamable HTTP 14 | transport](/specification/2025-03-26/basic/transports#streamable-http)** (PR 15 | [#206](https://github.com/modelcontextprotocol/specification/pull/206)) 16 | 1. Added support for JSON-RPC **[batching](https://www.jsonrpc.org/specification#batch)** 17 | (PR [#228](https://github.com/modelcontextprotocol/specification/pull/228)) 18 | 1. Added comprehensive **tool annotations** for better describing tool behavior, like 19 | whether it is read-only or destructive (PR 20 | [#185](https://github.com/modelcontextprotocol/specification/pull/185)) 21 | 22 | ## Other schema changes 23 | 24 | - Added `message` field to `ProgressNotification` to provide descriptive status updates 25 | - Added support for audio data, joining the existing text and image content types 26 | - Added `completions` capability to explicitly indicate support for argument 27 | autocompletion suggestions 28 | 29 | See 30 | [the updated schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2025-03-26/schema.ts) 31 | for more details. 32 | 33 | ## Full changelog 34 | 35 | For a complete list of all changes that have been made since the last protocol revision, 36 | [see GitHub](https://github.com/modelcontextprotocol/specification/compare/2024-11-05...2025-03-26). 37 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/client/roots.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Roots 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for clients to expose 8 | filesystem "roots" to servers. Roots define the boundaries of where servers can operate 9 | within the filesystem, allowing them to understand which directories and files they have 10 | access to. Servers can request the list of roots from supporting clients and receive 11 | notifications when that list changes. 12 | 13 | ## User Interaction Model 14 | 15 | Roots in MCP are typically exposed through workspace or project configuration interfaces. 16 | 17 | For example, implementations could offer a workspace/project picker that allows users to 18 | select directories and files the server should have access to. This can be combined with 19 | automatic workspace detection from version control systems or project files. 20 | 21 | However, implementations are free to expose roots through any interface pattern that 22 | suits their needs—the protocol itself does not mandate any specific user 23 | interaction model. 24 | 25 | ## Capabilities 26 | 27 | Clients that support roots **MUST** declare the `roots` capability during 28 | [initialization](/specification/2025-03-26/basic/lifecycle#initialization): 29 | 30 | ```json 31 | { 32 | "capabilities": { 33 | "roots": { 34 | "listChanged": true 35 | } 36 | } 37 | } 38 | ``` 39 | 40 | `listChanged` indicates whether the client will emit notifications when the list of roots 41 | changes. 42 | 43 | ## Protocol Messages 44 | 45 | ### Listing Roots 46 | 47 | To retrieve roots, servers send a `roots/list` request: 48 | 49 | **Request:** 50 | 51 | ```json 52 | { 53 | "jsonrpc": "2.0", 54 | "id": 1, 55 | "method": "roots/list" 56 | } 57 | ``` 58 | 59 | **Response:** 60 | 61 | ```json 62 | { 63 | "jsonrpc": "2.0", 64 | "id": 1, 65 | "result": { 66 | "roots": [ 67 | { 68 | "uri": "file:///home/user/projects/myproject", 69 | "name": "My Project" 70 | } 71 | ] 72 | } 73 | } 74 | ``` 75 | 76 | ### Root List Changes 77 | 78 | When roots change, clients that support `listChanged` **MUST** send a notification: 79 | 80 | ```json 81 | { 82 | "jsonrpc": "2.0", 83 | "method": "notifications/roots/list_changed" 84 | } 85 | ``` 86 | 87 | ## Message Flow 88 | 89 | ```mermaid 90 | sequenceDiagram 91 | participant Server 92 | participant Client 93 | 94 | Note over Server,Client: Discovery 95 | Server->>Client: roots/list 96 | Client-->>Server: Available roots 97 | 98 | Note over Server,Client: Changes 99 | Client--)Server: notifications/roots/list_changed 100 | Server->>Client: roots/list 101 | Client-->>Server: Updated roots 102 | ``` 103 | 104 | ## Data Types 105 | 106 | ### Root 107 | 108 | A root definition includes: 109 | 110 | - `uri`: Unique identifier for the root. This **MUST** be a `file://` URI in the current 111 | specification. 112 | - `name`: Optional human-readable name for display purposes. 113 | 114 | Example roots for different use cases: 115 | 116 | #### Project Directory 117 | 118 | ```json 119 | { 120 | "uri": "file:///home/user/projects/myproject", 121 | "name": "My Project" 122 | } 123 | ``` 124 | 125 | #### Multiple Repositories 126 | 127 | ```json 128 | [ 129 | { 130 | "uri": "file:///home/user/repos/frontend", 131 | "name": "Frontend Repository" 132 | }, 133 | { 134 | "uri": "file:///home/user/repos/backend", 135 | "name": "Backend Repository" 136 | } 137 | ] 138 | ``` 139 | 140 | ## Error Handling 141 | 142 | Clients **SHOULD** return standard JSON-RPC errors for common failure cases: 143 | 144 | - Client does not support roots: `-32601` (Method not found) 145 | - Internal errors: `-32603` 146 | 147 | Example error: 148 | 149 | ```json 150 | { 151 | "jsonrpc": "2.0", 152 | "id": 1, 153 | "error": { 154 | "code": -32601, 155 | "message": "Roots not supported", 156 | "data": { 157 | "reason": "Client does not have roots capability" 158 | } 159 | } 160 | } 161 | ``` 162 | 163 | ## Security Considerations 164 | 165 | 1. Clients **MUST**: 166 | 167 | - Only expose roots with appropriate permissions 168 | - Validate all root URIs to prevent path traversal 169 | - Implement proper access controls 170 | - Monitor root accessibility 171 | 172 | 2. Servers **SHOULD**: 173 | - Handle cases where roots become unavailable 174 | - Respect root boundaries during operations 175 | - Validate all paths against provided roots 176 | 177 | ## Implementation Guidelines 178 | 179 | 1. Clients **SHOULD**: 180 | 181 | - Prompt users for consent before exposing roots to servers 182 | - Provide clear user interfaces for root management 183 | - Validate root accessibility before exposing 184 | - Monitor for root changes 185 | 186 | 2. Servers **SHOULD**: 187 | - Check for roots capability before usage 188 | - Handle root list changes gracefully 189 | - Respect root boundaries in operations 190 | - Cache root information appropriately 191 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/client/sampling.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Sampling 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to request LLM 8 | sampling ("completions" or "generations") from language models via clients. This flow 9 | allows clients to maintain control over model access, selection, and permissions while 10 | enabling servers to leverage AI capabilities—with no server API keys necessary. 11 | Servers can request text, audio, or image-based interactions and optionally include 12 | context from MCP servers in their prompts. 13 | 14 | ## User Interaction Model 15 | 16 | Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to 17 | occur _nested_ inside other MCP server features. 18 | 19 | Implementations are free to expose sampling through any interface pattern that suits 20 | their needs—the protocol itself does not mandate any specific user interaction 21 | model. 22 | 23 | 24 | For trust & safety and security, there **SHOULD** always 25 | be a human in the loop with the ability to deny sampling requests. 26 | 27 | Applications **SHOULD**: 28 | 29 | - Provide UI that makes it easy and intuitive to review sampling requests 30 | - Allow users to view and edit prompts before sending 31 | - Present generated responses for review before delivery 32 | 33 | 34 | ## Capabilities 35 | 36 | Clients that support sampling **MUST** declare the `sampling` capability during 37 | [initialization](/specification/2025-03-26/basic/lifecycle#initialization): 38 | 39 | ```json 40 | { 41 | "capabilities": { 42 | "sampling": {} 43 | } 44 | } 45 | ``` 46 | 47 | ## Protocol Messages 48 | 49 | ### Creating Messages 50 | 51 | To request a language model generation, servers send a `sampling/createMessage` request: 52 | 53 | **Request:** 54 | 55 | ```json 56 | { 57 | "jsonrpc": "2.0", 58 | "id": 1, 59 | "method": "sampling/createMessage", 60 | "params": { 61 | "messages": [ 62 | { 63 | "role": "user", 64 | "content": { 65 | "type": "text", 66 | "text": "What is the capital of France?" 67 | } 68 | } 69 | ], 70 | "modelPreferences": { 71 | "hints": [ 72 | { 73 | "name": "claude-3-sonnet" 74 | } 75 | ], 76 | "intelligencePriority": 0.8, 77 | "speedPriority": 0.5 78 | }, 79 | "systemPrompt": "You are a helpful assistant.", 80 | "maxTokens": 100 81 | } 82 | } 83 | ``` 84 | 85 | **Response:** 86 | 87 | ```json 88 | { 89 | "jsonrpc": "2.0", 90 | "id": 1, 91 | "result": { 92 | "role": "assistant", 93 | "content": { 94 | "type": "text", 95 | "text": "The capital of France is Paris." 96 | }, 97 | "model": "claude-3-sonnet-20240307", 98 | "stopReason": "endTurn" 99 | } 100 | } 101 | ``` 102 | 103 | ## Message Flow 104 | 105 | ```mermaid 106 | sequenceDiagram 107 | participant Server 108 | participant Client 109 | participant User 110 | participant LLM 111 | 112 | Note over Server,Client: Server initiates sampling 113 | Server->>Client: sampling/createMessage 114 | 115 | Note over Client,User: Human-in-the-loop review 116 | Client->>User: Present request for approval 117 | User-->>Client: Review and approve/modify 118 | 119 | Note over Client,LLM: Model interaction 120 | Client->>LLM: Forward approved request 121 | LLM-->>Client: Return generation 122 | 123 | Note over Client,User: Response review 124 | Client->>User: Present response for approval 125 | User-->>Client: Review and approve/modify 126 | 127 | Note over Server,Client: Complete request 128 | Client-->>Server: Return approved response 129 | ``` 130 | 131 | ## Data Types 132 | 133 | ### Messages 134 | 135 | Sampling messages can contain: 136 | 137 | #### Text Content 138 | 139 | ```json 140 | { 141 | "type": "text", 142 | "text": "The message content" 143 | } 144 | ``` 145 | 146 | #### Image Content 147 | 148 | ```json 149 | { 150 | "type": "image", 151 | "data": "base64-encoded-image-data", 152 | "mimeType": "image/jpeg" 153 | } 154 | ``` 155 | 156 | #### Audio Content 157 | 158 | ```json 159 | { 160 | "type": "audio", 161 | "data": "base64-encoded-audio-data", 162 | "mimeType": "audio/wav" 163 | } 164 | ``` 165 | 166 | ### Model Preferences 167 | 168 | Model selection in MCP requires careful abstraction since servers and clients may use 169 | different AI providers with distinct model offerings. A server cannot simply request a 170 | specific model by name since the client may not have access to that exact model or may 171 | prefer to use a different provider's equivalent model. 172 | 173 | To solve this, MCP implements a preference system that combines abstract capability 174 | priorities with optional model hints: 175 | 176 | #### Capability Priorities 177 | 178 | Servers express their needs through three normalized priority values (0-1): 179 | 180 | - `costPriority`: How important is minimizing costs? Higher values prefer cheaper models. 181 | - `speedPriority`: How important is low latency? Higher values prefer faster models. 182 | - `intelligencePriority`: How important are advanced capabilities? Higher values prefer 183 | more capable models. 184 | 185 | #### Model Hints 186 | 187 | While priorities help select models based on characteristics, `hints` allow servers to 188 | suggest specific models or model families: 189 | 190 | - Hints are treated as substrings that can match model names flexibly 191 | - Multiple hints are evaluated in order of preference 192 | - Clients **MAY** map hints to equivalent models from different providers 193 | - Hints are advisory—clients make final model selection 194 | 195 | For example: 196 | 197 | ```json 198 | { 199 | "hints": [ 200 | { "name": "claude-3-sonnet" }, // Prefer Sonnet-class models 201 | { "name": "claude" } // Fall back to any Claude model 202 | ], 203 | "costPriority": 0.3, // Cost is less important 204 | "speedPriority": 0.8, // Speed is very important 205 | "intelligencePriority": 0.5 // Moderate capability needs 206 | } 207 | ``` 208 | 209 | The client processes these preferences to select an appropriate model from its available 210 | options. For instance, if the client doesn't have access to Claude models but has Gemini, 211 | it might map the sonnet hint to `gemini-1.5-pro` based on similar capabilities. 212 | 213 | ## Error Handling 214 | 215 | Clients **SHOULD** return errors for common failure cases: 216 | 217 | Example error: 218 | 219 | ```json 220 | { 221 | "jsonrpc": "2.0", 222 | "id": 1, 223 | "error": { 224 | "code": -1, 225 | "message": "User rejected sampling request" 226 | } 227 | } 228 | ``` 229 | 230 | ## Security Considerations 231 | 232 | 1. Clients **SHOULD** implement user approval controls 233 | 2. Both parties **SHOULD** validate message content 234 | 3. Clients **SHOULD** respect model preference hints 235 | 4. Clients **SHOULD** implement rate limiting 236 | 5. Both parties **MUST** handle sensitive data appropriately 237 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Specification 3 | --- 4 | 5 | [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that 6 | enables seamless integration between LLM applications and external data sources and 7 | tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating 8 | custom AI workflows, MCP provides a standardized way to connect LLMs with the context 9 | they need. 10 | 11 | This specification defines the authoritative protocol requirements, based on the 12 | TypeScript schema in 13 | [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-03-26/schema.ts). 14 | 15 | For implementation guides and examples, visit 16 | [modelcontextprotocol.io](https://modelcontextprotocol.io). 17 | 18 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 19 | NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 20 | interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) 21 | [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)] 22 | [[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)] when, and only when, they 23 | appear in all capitals, as shown here. 24 | 25 | ## Overview 26 | 27 | MCP provides a standardized way for applications to: 28 | 29 | - Share contextual information with language models 30 | - Expose tools and capabilities to AI systems 31 | - Build composable integrations and workflows 32 | 33 | The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish 34 | communication between: 35 | 36 | - **Hosts**: LLM applications that initiate connections 37 | - **Clients**: Connectors within the host application 38 | - **Servers**: Services that provide context and capabilities 39 | 40 | MCP takes some inspiration from the 41 | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which 42 | standardizes how to add support for programming languages across a whole ecosystem of 43 | development tools. In a similar way, MCP standardizes how to integrate additional context 44 | and tools into the ecosystem of AI applications. 45 | 46 | ## Key Details 47 | 48 | ### Base Protocol 49 | 50 | - [JSON-RPC](https://www.jsonrpc.org/) message format 51 | - Stateful connections 52 | - Server and client capability negotiation 53 | 54 | ### Features 55 | 56 | Servers offer any of the following features to clients: 57 | 58 | - **Resources**: Context and data, for the user or the AI model to use 59 | - **Prompts**: Templated messages and workflows for users 60 | - **Tools**: Functions for the AI model to execute 61 | 62 | Clients may offer the following feature to servers: 63 | 64 | - **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions 65 | 66 | ### Additional Utilities 67 | 68 | - Configuration 69 | - Progress tracking 70 | - Cancellation 71 | - Error reporting 72 | - Logging 73 | 74 | ## Security and Trust & Safety 75 | 76 | The Model Context Protocol enables powerful capabilities through arbitrary data access 77 | and code execution paths. With this power comes important security and trust 78 | considerations that all implementors must carefully address. 79 | 80 | ### Key Principles 81 | 82 | 1. **User Consent and Control** 83 | 84 | - Users must explicitly consent to and understand all data access and operations 85 | - Users must retain control over what data is shared and what actions are taken 86 | - Implementors should provide clear UIs for reviewing and authorizing activities 87 | 88 | 2. **Data Privacy** 89 | 90 | - Hosts must obtain explicit user consent before exposing user data to servers 91 | - Hosts must not transmit resource data elsewhere without user consent 92 | - User data should be protected with appropriate access controls 93 | 94 | 3. **Tool Safety** 95 | 96 | - Tools represent arbitrary code execution and must be treated with appropriate 97 | caution. 98 | - In particular, descriptions of tool behavior such as annotations should be 99 | considered untrusted, unless obtained from a trusted server. 100 | - Hosts must obtain explicit user consent before invoking any tool 101 | - Users should understand what each tool does before authorizing its use 102 | 103 | 4. **LLM Sampling Controls** 104 | - Users must explicitly approve any LLM sampling requests 105 | - Users should control: 106 | - Whether sampling occurs at all 107 | - The actual prompt that will be sent 108 | - What results the server can see 109 | - The protocol intentionally limits server visibility into prompts 110 | 111 | ### Implementation Guidelines 112 | 113 | While MCP itself cannot enforce these security principles at the protocol level, 114 | implementors **SHOULD**: 115 | 116 | 1. Build robust consent and authorization flows into their applications 117 | 2. Provide clear documentation of security implications 118 | 3. Implement appropriate access controls and data protections 119 | 4. Follow security best practices in their integrations 120 | 5. Consider privacy implications in their feature designs 121 | 122 | ## Learn More 123 | 124 | Explore the detailed specification for each protocol component: 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/server/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overview 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | Servers provide the fundamental building blocks for adding context to language models via 8 | MCP. These primitives enable rich interactions between clients, servers, and language 9 | models: 10 | 11 | - **Prompts**: Pre-defined templates or instructions that guide language model 12 | interactions 13 | - **Resources**: Structured data or content that provides additional context to the model 14 | - **Tools**: Executable functions that allow models to perform actions or retrieve 15 | information 16 | 17 | Each primitive can be summarized in the following control hierarchy: 18 | 19 | | Primitive | Control | Description | Example | 20 | | --------- | ---------------------- | -------------------------------------------------- | ------------------------------- | 21 | | Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options | 22 | | Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history | 23 | | Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing | 24 | 25 | Explore these key primitives in more detail below: 26 | 27 | 28 | 29 | 30 | 31 | 32 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/server/resource-picker.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/specification/2025-03-26/server/resource-picker.png -------------------------------------------------------------------------------- /docs/specification/2025-03-26/server/slash-command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/specification/2025-03-26/server/slash-command.png -------------------------------------------------------------------------------- /docs/specification/2025-03-26/server/utilities/completion.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Completion 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to offer 8 | argument autocompletion suggestions for prompts and resource URIs. This enables rich, 9 | IDE-like experiences where users receive contextual suggestions while entering argument 10 | values. 11 | 12 | ## User Interaction Model 13 | 14 | Completion in MCP is designed to support interactive user experiences similar to IDE code 15 | completion. 16 | 17 | For example, applications may show completion suggestions in a dropdown or popup menu as 18 | users type, with the ability to filter and select from available options. 19 | 20 | However, implementations are free to expose completion through any interface pattern that 21 | suits their needs—the protocol itself does not mandate any specific user 22 | interaction model. 23 | 24 | ## Capabilities 25 | 26 | Servers that support completions **MUST** declare the `completions` capability: 27 | 28 | ```json 29 | { 30 | "capabilities": { 31 | "completions": {} 32 | } 33 | } 34 | ``` 35 | 36 | ## Protocol Messages 37 | 38 | ### Requesting Completions 39 | 40 | To get completion suggestions, clients send a `completion/complete` request specifying 41 | what is being completed through a reference type: 42 | 43 | **Request:** 44 | 45 | ```json 46 | { 47 | "jsonrpc": "2.0", 48 | "id": 1, 49 | "method": "completion/complete", 50 | "params": { 51 | "ref": { 52 | "type": "ref/prompt", 53 | "name": "code_review" 54 | }, 55 | "argument": { 56 | "name": "language", 57 | "value": "py" 58 | } 59 | } 60 | } 61 | ``` 62 | 63 | **Response:** 64 | 65 | ```json 66 | { 67 | "jsonrpc": "2.0", 68 | "id": 1, 69 | "result": { 70 | "completion": { 71 | "values": ["python", "pytorch", "pyside"], 72 | "total": 10, 73 | "hasMore": true 74 | } 75 | } 76 | } 77 | ``` 78 | 79 | ### Reference Types 80 | 81 | The protocol supports two types of completion references: 82 | 83 | | Type | Description | Example | 84 | | -------------- | --------------------------- | --------------------------------------------------- | 85 | | `ref/prompt` | References a prompt by name | `{"type": "ref/prompt", "name": "code_review"}` | 86 | | `ref/resource` | References a resource URI | `{"type": "ref/resource", "uri": "file:///{path}"}` | 87 | 88 | ### Completion Results 89 | 90 | Servers return an array of completion values ranked by relevance, with: 91 | 92 | - Maximum 100 items per response 93 | - Optional total number of available matches 94 | - Boolean indicating if additional results exist 95 | 96 | ## Message Flow 97 | 98 | ```mermaid 99 | sequenceDiagram 100 | participant Client 101 | participant Server 102 | 103 | Note over Client: User types argument 104 | Client->>Server: completion/complete 105 | Server-->>Client: Completion suggestions 106 | 107 | Note over Client: User continues typing 108 | Client->>Server: completion/complete 109 | Server-->>Client: Refined suggestions 110 | ``` 111 | 112 | ## Data Types 113 | 114 | ### CompleteRequest 115 | 116 | - `ref`: A `PromptReference` or `ResourceReference` 117 | - `argument`: Object containing: 118 | - `name`: Argument name 119 | - `value`: Current value 120 | 121 | ### CompleteResult 122 | 123 | - `completion`: Object containing: 124 | - `values`: Array of suggestions (max 100) 125 | - `total`: Optional total matches 126 | - `hasMore`: Additional results flag 127 | 128 | ## Error Handling 129 | 130 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases: 131 | 132 | - Method not found: `-32601` (Capability not supported) 133 | - Invalid prompt name: `-32602` (Invalid params) 134 | - Missing required arguments: `-32602` (Invalid params) 135 | - Internal errors: `-32603` (Internal error) 136 | 137 | ## Implementation Considerations 138 | 139 | 1. Servers **SHOULD**: 140 | 141 | - Return suggestions sorted by relevance 142 | - Implement fuzzy matching where appropriate 143 | - Rate limit completion requests 144 | - Validate all inputs 145 | 146 | 2. Clients **SHOULD**: 147 | - Debounce rapid completion requests 148 | - Cache completion results where appropriate 149 | - Handle missing or partial results gracefully 150 | 151 | ## Security 152 | 153 | Implementations **MUST**: 154 | 155 | - Validate all completion inputs 156 | - Implement appropriate rate limiting 157 | - Control access to sensitive suggestions 158 | - Prevent completion-based information disclosure 159 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/server/utilities/logging.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Logging 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to send 8 | structured log messages to clients. Clients can control logging verbosity by setting 9 | minimum log levels, with servers sending notifications containing severity levels, 10 | optional logger names, and arbitrary JSON-serializable data. 11 | 12 | ## User Interaction Model 13 | 14 | Implementations are free to expose logging through any interface pattern that suits their 15 | needs—the protocol itself does not mandate any specific user interaction model. 16 | 17 | ## Capabilities 18 | 19 | Servers that emit log message notifications **MUST** declare the `logging` capability: 20 | 21 | ```json 22 | { 23 | "capabilities": { 24 | "logging": {} 25 | } 26 | } 27 | ``` 28 | 29 | ## Log Levels 30 | 31 | The protocol follows the standard syslog severity levels specified in 32 | [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1): 33 | 34 | | Level | Description | Example Use Case | 35 | | --------- | -------------------------------- | -------------------------- | 36 | | debug | Detailed debugging information | Function entry/exit points | 37 | | info | General informational messages | Operation progress updates | 38 | | notice | Normal but significant events | Configuration changes | 39 | | warning | Warning conditions | Deprecated feature usage | 40 | | error | Error conditions | Operation failures | 41 | | critical | Critical conditions | System component failures | 42 | | alert | Action must be taken immediately | Data corruption detected | 43 | | emergency | System is unusable | Complete system failure | 44 | 45 | ## Protocol Messages 46 | 47 | ### Setting Log Level 48 | 49 | To configure the minimum log level, clients **MAY** send a `logging/setLevel` request: 50 | 51 | **Request:** 52 | 53 | ```json 54 | { 55 | "jsonrpc": "2.0", 56 | "id": 1, 57 | "method": "logging/setLevel", 58 | "params": { 59 | "level": "info" 60 | } 61 | } 62 | ``` 63 | 64 | ### Log Message Notifications 65 | 66 | Servers send log messages using `notifications/message` notifications: 67 | 68 | ```json 69 | { 70 | "jsonrpc": "2.0", 71 | "method": "notifications/message", 72 | "params": { 73 | "level": "error", 74 | "logger": "database", 75 | "data": { 76 | "error": "Connection failed", 77 | "details": { 78 | "host": "localhost", 79 | "port": 5432 80 | } 81 | } 82 | } 83 | } 84 | ``` 85 | 86 | ## Message Flow 87 | 88 | ```mermaid 89 | sequenceDiagram 90 | participant Client 91 | participant Server 92 | 93 | Note over Client,Server: Configure Logging 94 | Client->>Server: logging/setLevel (info) 95 | Server-->>Client: Empty Result 96 | 97 | Note over Client,Server: Server Activity 98 | Server--)Client: notifications/message (info) 99 | Server--)Client: notifications/message (warning) 100 | Server--)Client: notifications/message (error) 101 | 102 | Note over Client,Server: Level Change 103 | Client->>Server: logging/setLevel (error) 104 | Server-->>Client: Empty Result 105 | Note over Server: Only sends error level
and above 106 | ``` 107 | 108 | ## Error Handling 109 | 110 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases: 111 | 112 | - Invalid log level: `-32602` (Invalid params) 113 | - Configuration errors: `-32603` (Internal error) 114 | 115 | ## Implementation Considerations 116 | 117 | 1. Servers **SHOULD**: 118 | 119 | - Rate limit log messages 120 | - Include relevant context in data field 121 | - Use consistent logger names 122 | - Remove sensitive information 123 | 124 | 2. Clients **MAY**: 125 | - Present log messages in the UI 126 | - Implement log filtering/search 127 | - Display severity visually 128 | - Persist log messages 129 | 130 | ## Security 131 | 132 | 1. Log messages **MUST NOT** contain: 133 | 134 | - Credentials or secrets 135 | - Personal identifying information 136 | - Internal system details that could aid attacks 137 | 138 | 2. Implementations **SHOULD**: 139 | - Rate limit messages 140 | - Validate all data fields 141 | - Control log access 142 | - Monitor for sensitive content 143 | -------------------------------------------------------------------------------- /docs/specification/2025-03-26/server/utilities/pagination.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Pagination 3 | --- 4 | 5 | **Protocol Revision**: 2025-03-26 6 | 7 | The Model Context Protocol (MCP) supports paginating list operations that may return 8 | large result sets. Pagination allows servers to yield results in smaller chunks rather 9 | than all at once. 10 | 11 | Pagination is especially important when connecting to external services over the 12 | internet, but also useful for local integrations to avoid performance issues with large 13 | data sets. 14 | 15 | ## Pagination Model 16 | 17 | Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages. 18 | 19 | - The **cursor** is an opaque string token, representing a position in the result set 20 | - **Page size** is determined by the server, and clients **MUST NOT** assume a fixed page 21 | size 22 | 23 | ## Response Format 24 | 25 | Pagination starts when the server sends a **response** that includes: 26 | 27 | - The current page of results 28 | - An optional `nextCursor` field if more results exist 29 | 30 | ```json 31 | { 32 | "jsonrpc": "2.0", 33 | "id": "123", 34 | "result": { 35 | "resources": [...], 36 | "nextCursor": "eyJwYWdlIjogM30=" 37 | } 38 | } 39 | ``` 40 | 41 | ## Request Format 42 | 43 | After receiving a cursor, the client can _continue_ paginating by issuing a request 44 | including that cursor: 45 | 46 | ```json 47 | { 48 | "jsonrpc": "2.0", 49 | "method": "resources/list", 50 | "params": { 51 | "cursor": "eyJwYWdlIjogMn0=" 52 | } 53 | } 54 | ``` 55 | 56 | ## Pagination Flow 57 | 58 | ```mermaid 59 | sequenceDiagram 60 | participant Client 61 | participant Server 62 | 63 | Client->>Server: List Request (no cursor) 64 | loop Pagination Loop 65 | Server-->>Client: Page of results + nextCursor 66 | Client->>Server: List Request (with cursor) 67 | end 68 | ``` 69 | 70 | ## Operations Supporting Pagination 71 | 72 | The following MCP operations support pagination: 73 | 74 | - `resources/list` - List available resources 75 | - `resources/templates/list` - List resource templates 76 | - `prompts/list` - List available prompts 77 | - `tools/list` - List available tools 78 | 79 | ## Implementation Guidelines 80 | 81 | 1. Servers **SHOULD**: 82 | 83 | - Provide stable cursors 84 | - Handle invalid cursors gracefully 85 | 86 | 2. Clients **SHOULD**: 87 | 88 | - Treat a missing `nextCursor` as the end of results 89 | - Support both paginated and non-paginated flows 90 | 91 | 3. Clients **MUST** treat cursors as opaque tokens: 92 | - Don't make assumptions about cursor format 93 | - Don't attempt to parse or modify cursors 94 | - Don't persist cursors across sessions 95 | 96 | ## Error Handling 97 | 98 | Invalid cursors **SHOULD** result in an error with code -32602 (Invalid params). 99 | -------------------------------------------------------------------------------- /docs/specification/contributing.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Contributions" 3 | weight: 20 4 | cascade: 5 | type: docs 6 | breadcrumbs: false 7 | --- 8 | 9 | We welcome contributions from the community! Please review our 10 | [contributing guidelines](https://github.com/modelcontextprotocol/specification/blob/main/CONTRIBUTING.md) 11 | for details on how to submit changes. 12 | 13 | All contributors must adhere to our 14 | [Code of Conduct](https://github.com/modelcontextprotocol/specification/blob/main/CODE_OF_CONDUCT.md). 15 | 16 | For questions and discussions, please use 17 | [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions). 18 | -------------------------------------------------------------------------------- /docs/specification/draft/architecture/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Architecture 3 | --- 4 | 5 | The Model Context Protocol (MCP) follows a client-host-server architecture where each 6 | host can run multiple client instances. This architecture enables users to integrate AI 7 | capabilities across applications while maintaining clear security boundaries and 8 | isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused 9 | on context exchange and sampling coordination between clients and servers. 10 | 11 | ## Core Components 12 | 13 | ```mermaid 14 | graph LR 15 | subgraph "Application Host Process" 16 | H[Host] 17 | C1[Client 1] 18 | C2[Client 2] 19 | C3[Client 3] 20 | H --> C1 21 | H --> C2 22 | H --> C3 23 | end 24 | 25 | subgraph "Local machine" 26 | S1[Server 1
Files & Git] 27 | S2[Server 2
Database] 28 | R1[("Local
Resource A")] 29 | R2[("Local
Resource B")] 30 | 31 | C1 --> S1 32 | C2 --> S2 33 | S1 <--> R1 34 | S2 <--> R2 35 | end 36 | 37 | subgraph "Internet" 38 | S3[Server 3
External APIs] 39 | R3[("Remote
Resource C")] 40 | 41 | C3 --> S3 42 | S3 <--> R3 43 | end 44 | ``` 45 | 46 | ### Host 47 | 48 | The host process acts as the container and coordinator: 49 | 50 | - Creates and manages multiple client instances 51 | - Controls client connection permissions and lifecycle 52 | - Enforces security policies and consent requirements 53 | - Handles user authorization decisions 54 | - Coordinates AI/LLM integration and sampling 55 | - Manages context aggregation across clients 56 | 57 | ### Clients 58 | 59 | Each client is created by the host and maintains an isolated server connection: 60 | 61 | - Establishes one stateful session per server 62 | - Handles protocol negotiation and capability exchange 63 | - Routes protocol messages bidirectionally 64 | - Manages subscriptions and notifications 65 | - Maintains security boundaries between servers 66 | 67 | A host application creates and manages multiple clients, with each client having a 1:1 68 | relationship with a particular server. 69 | 70 | ### Servers 71 | 72 | Servers provide specialized context and capabilities: 73 | 74 | - Expose resources, tools and prompts via MCP primitives 75 | - Operate independently with focused responsibilities 76 | - Request sampling through client interfaces 77 | - Must respect security constraints 78 | - Can be local processes or remote services 79 | 80 | ## Design Principles 81 | 82 | MCP is built on several key design principles that inform its architecture and 83 | implementation: 84 | 85 | 1. **Servers should be extremely easy to build** 86 | 87 | - Host applications handle complex orchestration responsibilities 88 | - Servers focus on specific, well-defined capabilities 89 | - Simple interfaces minimize implementation overhead 90 | - Clear separation enables maintainable code 91 | 92 | 2. **Servers should be highly composable** 93 | 94 | - Each server provides focused functionality in isolation 95 | - Multiple servers can be combined seamlessly 96 | - Shared protocol enables interoperability 97 | - Modular design supports extensibility 98 | 99 | 3. **Servers should not be able to read the whole conversation, nor "see into" other 100 | servers** 101 | 102 | - Servers receive only necessary contextual information 103 | - Full conversation history stays with the host 104 | - Each server connection maintains isolation 105 | - Cross-server interactions are controlled by the host 106 | - Host process enforces security boundaries 107 | 108 | 4. **Features can be added to servers and clients progressively** 109 | - Core protocol provides minimal required functionality 110 | - Additional capabilities can be negotiated as needed 111 | - Servers and clients evolve independently 112 | - Protocol designed for future extensibility 113 | - Backwards compatibility is maintained 114 | 115 | ## Capability Negotiation 116 | 117 | The Model Context Protocol uses a capability-based negotiation system where clients and 118 | servers explicitly declare their supported features during initialization. Capabilities 119 | determine which protocol features and primitives are available during a session. 120 | 121 | - Servers declare capabilities like resource subscriptions, tool support, and prompt 122 | templates 123 | - Clients declare capabilities like sampling support and notification handling 124 | - Both parties must respect declared capabilities throughout the session 125 | - Additional capabilities can be negotiated through extensions to the protocol 126 | 127 | ```mermaid 128 | sequenceDiagram 129 | participant Host 130 | participant Client 131 | participant Server 132 | 133 | Host->>+Client: Initialize client 134 | Client->>+Server: Initialize session with capabilities 135 | Server-->>Client: Respond with supported capabilities 136 | 137 | Note over Host,Server: Active Session with Negotiated Features 138 | 139 | loop Client Requests 140 | Host->>Client: User- or model-initiated action 141 | Client->>Server: Request (tools/resources) 142 | Server-->>Client: Response 143 | Client-->>Host: Update UI or respond to model 144 | end 145 | 146 | loop Server Requests 147 | Server->>Client: Request (sampling) 148 | Client->>Host: Forward to AI 149 | Host-->>Client: AI response 150 | Client-->>Server: Response 151 | end 152 | 153 | loop Notifications 154 | Server--)Client: Resource updates 155 | Client--)Server: Status changes 156 | end 157 | 158 | Host->>Client: Terminate 159 | Client->>-Server: End session 160 | deactivate Server 161 | ``` 162 | 163 | Each capability unlocks specific protocol features for use during the session. For 164 | example: 165 | 166 | - Implemented [server features](/specification/draft/server) must be advertised in the 167 | server's capabilities 168 | - Emitting resource subscription notifications requires the server to declare 169 | subscription support 170 | - Tool invocation requires the server to declare tool capabilities 171 | - [Sampling](/specification/draft/client) requires the client to declare support in its 172 | capabilities 173 | 174 | This capability negotiation ensures clients and servers have a clear understanding of 175 | supported functionality while maintaining protocol extensibility. 176 | -------------------------------------------------------------------------------- /docs/specification/draft/basic/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overview 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | The Model Context Protocol consists of several key components that work together: 8 | 9 | - **Base Protocol**: Core JSON-RPC message types 10 | - **Lifecycle Management**: Connection initialization, capability negotiation, and 11 | session control 12 | - **Server Features**: Resources, prompts, and tools exposed by servers 13 | - **Client Features**: Sampling and root directory lists provided by clients 14 | - **Utilities**: Cross-cutting concerns like logging and argument completion 15 | 16 | All implementations **MUST** support the base protocol and lifecycle management 17 | components. Other components **MAY** be implemented based on the specific needs of the 18 | application. 19 | 20 | These protocol layers establish clear separation of concerns while enabling rich 21 | interactions between clients and servers. The modular design allows implementations to 22 | support exactly the features they need. 23 | 24 | ## Messages 25 | 26 | All messages between MCP clients and servers **MUST** follow the 27 | [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines 28 | these types of messages: 29 | 30 | ### Requests 31 | 32 | Requests are sent from the client to the server or vice versa, to initiate an operation. 33 | 34 | ```typescript 35 | { 36 | jsonrpc: "2.0"; 37 | id: string | number; 38 | method: string; 39 | params?: { 40 | [key: string]: unknown; 41 | }; 42 | } 43 | ``` 44 | 45 | - Requests **MUST** include a string or integer ID. 46 | - Unlike base JSON-RPC, the ID **MUST NOT** be `null`. 47 | - The request ID **MUST NOT** have been previously used by the requestor within the same 48 | session. 49 | 50 | ### Responses 51 | 52 | Responses are sent in reply to requests, containing the result or error of the operation. 53 | 54 | ```typescript 55 | { 56 | jsonrpc: "2.0"; 57 | id: string | number; 58 | result?: { 59 | [key: string]: unknown; 60 | } 61 | error?: { 62 | code: number; 63 | message: string; 64 | data?: unknown; 65 | } 66 | } 67 | ``` 68 | 69 | - Responses **MUST** include the same ID as the request they correspond to. 70 | - **Responses** are further sub-categorized as either **successful results** or 71 | **errors**. Either a `result` or an `error` **MUST** be set. A response **MUST NOT** 72 | set both. 73 | - Results **MAY** follow any JSON object structure, while errors **MUST** include an 74 | error code and message at minimum. 75 | - Error codes **MUST** be integers. 76 | 77 | ### Notifications 78 | 79 | Notifications are sent from the client to the server or vice versa, as a one-way message. 80 | The receiver **MUST NOT** send a response. 81 | 82 | ```typescript 83 | { 84 | jsonrpc: "2.0"; 85 | method: string; 86 | params?: { 87 | [key: string]: unknown; 88 | }; 89 | } 90 | ``` 91 | 92 | - Notifications **MUST NOT** include an ID. 93 | 94 | ## Auth 95 | 96 | MCP provides an [Authorization](/specification/draft/basic/authorization) framework for use with HTTP. 97 | Implementations using an HTTP-based transport **SHOULD** conform to this specification, 98 | whereas implementations using STDIO transport **SHOULD NOT** follow this specification, 99 | and instead retrieve credentials from the environment. 100 | 101 | Additionally, clients and servers **MAY** negotiate their own custom authentication and 102 | authorization strategies. 103 | 104 | For further discussions and contributions to the evolution of MCP’s auth mechanisms, join 105 | us in 106 | [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions) 107 | to help shape the future of the protocol! 108 | 109 | ## Schema 110 | 111 | The full specification of the protocol is defined as a 112 | [TypeScript schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.ts). 113 | This is the source of truth for all protocol messages and structures. 114 | 115 | There is also a 116 | [JSON Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.json), 117 | which is automatically generated from the TypeScript source of truth, for use with 118 | various automated tooling. 119 | -------------------------------------------------------------------------------- /docs/specification/draft/basic/utilities/cancellation.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Cancellation 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | The Model Context Protocol (MCP) supports optional cancellation of in-progress requests 8 | through notification messages. Either side can send a cancellation notification to 9 | indicate that a previously-issued request should be terminated. 10 | 11 | ## Cancellation Flow 12 | 13 | When a party wants to cancel an in-progress request, it sends a `notifications/cancelled` 14 | notification containing: 15 | 16 | - The ID of the request to cancel 17 | - An optional reason string that can be logged or displayed 18 | 19 | ```json 20 | { 21 | "jsonrpc": "2.0", 22 | "method": "notifications/cancelled", 23 | "params": { 24 | "requestId": "123", 25 | "reason": "User requested cancellation" 26 | } 27 | } 28 | ``` 29 | 30 | ## Behavior Requirements 31 | 32 | 1. Cancellation notifications **MUST** only reference requests that: 33 | - Were previously issued in the same direction 34 | - Are believed to still be in-progress 35 | 2. The `initialize` request **MUST NOT** be cancelled by clients 36 | 3. Receivers of cancellation notifications **SHOULD**: 37 | - Stop processing the cancelled request 38 | - Free associated resources 39 | - Not send a response for the cancelled request 40 | 4. Receivers **MAY** ignore cancellation notifications if: 41 | - The referenced request is unknown 42 | - Processing has already completed 43 | - The request cannot be cancelled 44 | 5. The sender of the cancellation notification **SHOULD** ignore any response to the 45 | request that arrives afterward 46 | 47 | ## Timing Considerations 48 | 49 | Due to network latency, cancellation notifications may arrive after request processing 50 | has completed, and potentially after a response has already been sent. 51 | 52 | Both parties **MUST** handle these race conditions gracefully: 53 | 54 | ```mermaid 55 | sequenceDiagram 56 | participant Client 57 | participant Server 58 | 59 | Client->>Server: Request (ID: 123) 60 | Note over Server: Processing starts 61 | Client--)Server: notifications/cancelled (ID: 123) 62 | alt 63 | Note over Server: Processing may have
completed before
cancellation arrives 64 | else If not completed 65 | Note over Server: Stop processing 66 | end 67 | ``` 68 | 69 | ## Implementation Notes 70 | 71 | - Both parties **SHOULD** log cancellation reasons for debugging 72 | - Application UIs **SHOULD** indicate when cancellation is requested 73 | 74 | ## Error Handling 75 | 76 | Invalid cancellation notifications **SHOULD** be ignored: 77 | 78 | - Unknown request IDs 79 | - Already completed requests 80 | - Malformed notifications 81 | 82 | This maintains the "fire and forget" nature of notifications while allowing for race 83 | conditions in asynchronous communication. 84 | -------------------------------------------------------------------------------- /docs/specification/draft/basic/utilities/ping.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Ping 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | The Model Context Protocol includes an optional ping mechanism that allows either party 8 | to verify that their counterpart is still responsive and the connection is alive. 9 | 10 | ## Overview 11 | 12 | The ping functionality is implemented through a simple request/response pattern. Either 13 | the client or server can initiate a ping by sending a `ping` request. 14 | 15 | ## Message Format 16 | 17 | A ping request is a standard JSON-RPC request with no parameters: 18 | 19 | ```json 20 | { 21 | "jsonrpc": "2.0", 22 | "id": "123", 23 | "method": "ping" 24 | } 25 | ``` 26 | 27 | ## Behavior Requirements 28 | 29 | 1. The receiver **MUST** respond promptly with an empty response: 30 | 31 | ```json 32 | { 33 | "jsonrpc": "2.0", 34 | "id": "123", 35 | "result": {} 36 | } 37 | ``` 38 | 39 | 2. If no response is received within a reasonable timeout period, the sender **MAY**: 40 | - Consider the connection stale 41 | - Terminate the connection 42 | - Attempt reconnection procedures 43 | 44 | ## Usage Patterns 45 | 46 | ```mermaid 47 | sequenceDiagram 48 | participant Sender 49 | participant Receiver 50 | 51 | Sender->>Receiver: ping request 52 | Receiver->>Sender: empty response 53 | ``` 54 | 55 | ## Implementation Considerations 56 | 57 | - Implementations **SHOULD** periodically issue pings to detect connection health 58 | - The frequency of pings **SHOULD** be configurable 59 | - Timeouts **SHOULD** be appropriate for the network environment 60 | - Excessive pinging **SHOULD** be avoided to reduce network overhead 61 | 62 | ## Error Handling 63 | 64 | - Timeouts **SHOULD** be treated as connection failures 65 | - Multiple failed pings **MAY** trigger connection reset 66 | - Implementations **SHOULD** log ping failures for diagnostics 67 | -------------------------------------------------------------------------------- /docs/specification/draft/basic/utilities/progress.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Progress 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | The Model Context Protocol (MCP) supports optional progress tracking for long-running 8 | operations through notification messages. Either side can send progress notifications to 9 | provide updates about operation status. 10 | 11 | ## Progress Flow 12 | 13 | When a party wants to _receive_ progress updates for a request, it includes a 14 | `progressToken` in the request metadata. 15 | 16 | - Progress tokens **MUST** be a string or integer value 17 | - Progress tokens can be chosen by the sender using any means, but **MUST** be unique 18 | across all active requests. 19 | 20 | ```json 21 | { 22 | "jsonrpc": "2.0", 23 | "id": 1, 24 | "method": "some_method", 25 | "params": { 26 | "_meta": { 27 | "progressToken": "abc123" 28 | } 29 | } 30 | } 31 | ``` 32 | 33 | The receiver **MAY** then send progress notifications containing: 34 | 35 | - The original progress token 36 | - The current progress value so far 37 | - An optional "total" value 38 | - An optional "message" value 39 | 40 | ```json 41 | { 42 | "jsonrpc": "2.0", 43 | "method": "notifications/progress", 44 | "params": { 45 | "progressToken": "abc123", 46 | "progress": 50, 47 | "total": 100, 48 | "message": "Reticulating splines..." 49 | } 50 | } 51 | ``` 52 | 53 | - The `progress` value **MUST** increase with each notification, even if the total is 54 | unknown. 55 | - The `progress` and the `total` values **MAY** be floating point. 56 | - The `message` field **SHOULD** provide relevant human readable progress information. 57 | 58 | ## Behavior Requirements 59 | 60 | 1. Progress notifications **MUST** only reference tokens that: 61 | 62 | - Were provided in an active request 63 | - Are associated with an in-progress operation 64 | 65 | 2. Receivers of progress requests **MAY**: 66 | - Choose not to send any progress notifications 67 | - Send notifications at whatever frequency they deem appropriate 68 | - Omit the total value if unknown 69 | 70 | ```mermaid 71 | sequenceDiagram 72 | participant Sender 73 | participant Receiver 74 | 75 | Note over Sender,Receiver: Request with progress token 76 | Sender->>Receiver: Method request with progressToken 77 | 78 | Note over Sender,Receiver: Progress updates 79 | loop Progress Updates 80 | Receiver-->>Sender: Progress notification (0.2/1.0) 81 | Receiver-->>Sender: Progress notification (0.6/1.0) 82 | Receiver-->>Sender: Progress notification (1.0/1.0) 83 | end 84 | 85 | Note over Sender,Receiver: Operation complete 86 | Receiver->>Sender: Method response 87 | ``` 88 | 89 | ## Implementation Notes 90 | 91 | - Senders and receivers **SHOULD** track active progress tokens 92 | - Both parties **SHOULD** implement rate limiting to prevent flooding 93 | - Progress notifications **MUST** stop after completion 94 | -------------------------------------------------------------------------------- /docs/specification/draft/changelog.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Key Changes 3 | --- 4 | 5 | This document lists changes made to the Model Context Protocol (MCP) specification since 6 | the previous revision, [2025-03-26](/specification/2025-03-26). 7 | 8 | ## Major changes 9 | 10 | 1. Removed support for JSON-RPC **[batching](https://www.jsonrpc.org/specification#batch)** 11 | (PR [#416](https://github.com/modelcontextprotocol/specification/pull/416)) 12 | 2. Added support for [structured tool output](https://modelcontextprotocol.io/specification/draft/server/tools#structured-content) 13 | (PR [#371](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/371)) 14 | 3. Classified MCP servers as [OAuth Resource Servers](https://modelcontextprotocol.io/specification/draft/basic/authorization#2-3-authorization-server-discovery), adding protected resource metadata to discover the corresponding Authorization server. (PR [#338](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/338)) 15 | 4. Clarified [security considerations](https://modelcontextprotocol.io/specification/draft/basic/authorization#3-security-considerations) and best practices in the authorization spec and in a new [security best practices page](https://modelcontextprotocol.io/specification/draft/basic/security_best_practices). 16 | 5. Added support for **[elicitation](/specification/draft/client/elicitation)**, enabling 17 | servers to request additional information from users during interactions. (PR [#382](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/382)) 18 | 19 | ## Other schema changes 20 | 21 | ## Full changelog 22 | 23 | For a complete list of all changes that have been made since the last protocol revision, 24 | [see GitHub](https://github.com/modelcontextprotocol/specification/compare/2025-03-26...draft). 25 | -------------------------------------------------------------------------------- /docs/specification/draft/client/roots.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Roots 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for clients to expose 8 | filesystem "roots" to servers. Roots define the boundaries of where servers can operate 9 | within the filesystem, allowing them to understand which directories and files they have 10 | access to. Servers can request the list of roots from supporting clients and receive 11 | notifications when that list changes. 12 | 13 | ## User Interaction Model 14 | 15 | Roots in MCP are typically exposed through workspace or project configuration interfaces. 16 | 17 | For example, implementations could offer a workspace/project picker that allows users to 18 | select directories and files the server should have access to. This can be combined with 19 | automatic workspace detection from version control systems or project files. 20 | 21 | However, implementations are free to expose roots through any interface pattern that 22 | suits their needs—the protocol itself does not mandate any specific user 23 | interaction model. 24 | 25 | ## Capabilities 26 | 27 | Clients that support roots **MUST** declare the `roots` capability during 28 | [initialization](/specification/draft/basic/lifecycle#initialization): 29 | 30 | ```json 31 | { 32 | "capabilities": { 33 | "roots": { 34 | "listChanged": true 35 | } 36 | } 37 | } 38 | ``` 39 | 40 | `listChanged` indicates whether the client will emit notifications when the list of roots 41 | changes. 42 | 43 | ## Protocol Messages 44 | 45 | ### Listing Roots 46 | 47 | To retrieve roots, servers send a `roots/list` request: 48 | 49 | **Request:** 50 | 51 | ```json 52 | { 53 | "jsonrpc": "2.0", 54 | "id": 1, 55 | "method": "roots/list" 56 | } 57 | ``` 58 | 59 | **Response:** 60 | 61 | ```json 62 | { 63 | "jsonrpc": "2.0", 64 | "id": 1, 65 | "result": { 66 | "roots": [ 67 | { 68 | "uri": "file:///home/user/projects/myproject", 69 | "name": "My Project" 70 | } 71 | ] 72 | } 73 | } 74 | ``` 75 | 76 | ### Root List Changes 77 | 78 | When roots change, clients that support `listChanged` **MUST** send a notification: 79 | 80 | ```json 81 | { 82 | "jsonrpc": "2.0", 83 | "method": "notifications/roots/list_changed" 84 | } 85 | ``` 86 | 87 | ## Message Flow 88 | 89 | ```mermaid 90 | sequenceDiagram 91 | participant Server 92 | participant Client 93 | 94 | Note over Server,Client: Discovery 95 | Server->>Client: roots/list 96 | Client-->>Server: Available roots 97 | 98 | Note over Server,Client: Changes 99 | Client--)Server: notifications/roots/list_changed 100 | Server->>Client: roots/list 101 | Client-->>Server: Updated roots 102 | ``` 103 | 104 | ## Data Types 105 | 106 | ### Root 107 | 108 | A root definition includes: 109 | 110 | - `uri`: Unique identifier for the root. This **MUST** be a `file://` URI in the current 111 | specification. 112 | - `name`: Optional human-readable name for display purposes. 113 | 114 | Example roots for different use cases: 115 | 116 | #### Project Directory 117 | 118 | ```json 119 | { 120 | "uri": "file:///home/user/projects/myproject", 121 | "name": "My Project" 122 | } 123 | ``` 124 | 125 | #### Multiple Repositories 126 | 127 | ```json 128 | [ 129 | { 130 | "uri": "file:///home/user/repos/frontend", 131 | "name": "Frontend Repository" 132 | }, 133 | { 134 | "uri": "file:///home/user/repos/backend", 135 | "name": "Backend Repository" 136 | } 137 | ] 138 | ``` 139 | 140 | ## Error Handling 141 | 142 | Clients **SHOULD** return standard JSON-RPC errors for common failure cases: 143 | 144 | - Client does not support roots: `-32601` (Method not found) 145 | - Internal errors: `-32603` 146 | 147 | Example error: 148 | 149 | ```json 150 | { 151 | "jsonrpc": "2.0", 152 | "id": 1, 153 | "error": { 154 | "code": -32601, 155 | "message": "Roots not supported", 156 | "data": { 157 | "reason": "Client does not have roots capability" 158 | } 159 | } 160 | } 161 | ``` 162 | 163 | ## Security Considerations 164 | 165 | 1. Clients **MUST**: 166 | 167 | - Only expose roots with appropriate permissions 168 | - Validate all root URIs to prevent path traversal 169 | - Implement proper access controls 170 | - Monitor root accessibility 171 | 172 | 2. Servers **SHOULD**: 173 | - Handle cases where roots become unavailable 174 | - Respect root boundaries during operations 175 | - Validate all paths against provided roots 176 | 177 | ## Implementation Guidelines 178 | 179 | 1. Clients **SHOULD**: 180 | 181 | - Prompt users for consent before exposing roots to servers 182 | - Provide clear user interfaces for root management 183 | - Validate root accessibility before exposing 184 | - Monitor for root changes 185 | 186 | 2. Servers **SHOULD**: 187 | - Check for roots capability before usage 188 | - Handle root list changes gracefully 189 | - Respect root boundaries in operations 190 | - Cache root information appropriately 191 | -------------------------------------------------------------------------------- /docs/specification/draft/client/sampling.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Sampling 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to request LLM 8 | sampling ("completions" or "generations") from language models via clients. This flow 9 | allows clients to maintain control over model access, selection, and permissions while 10 | enabling servers to leverage AI capabilities—with no server API keys necessary. 11 | Servers can request text, audio, or image-based interactions and optionally include 12 | context from MCP servers in their prompts. 13 | 14 | ## User Interaction Model 15 | 16 | Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to 17 | occur _nested_ inside other MCP server features. 18 | 19 | Implementations are free to expose sampling through any interface pattern that suits 20 | their needs—the protocol itself does not mandate any specific user interaction 21 | model. 22 | 23 | 24 | For trust & safety and security, there **SHOULD** always 25 | be a human in the loop with the ability to deny sampling requests. 26 | 27 | Applications **SHOULD**: 28 | 29 | - Provide UI that makes it easy and intuitive to review sampling requests 30 | - Allow users to view and edit prompts before sending 31 | - Present generated responses for review before delivery 32 | 33 | 34 | ## Capabilities 35 | 36 | Clients that support sampling **MUST** declare the `sampling` capability during 37 | [initialization](/specification/draft/basic/lifecycle#initialization): 38 | 39 | ```json 40 | { 41 | "capabilities": { 42 | "sampling": {} 43 | } 44 | } 45 | ``` 46 | 47 | ## Protocol Messages 48 | 49 | ### Creating Messages 50 | 51 | To request a language model generation, servers send a `sampling/createMessage` request: 52 | 53 | **Request:** 54 | 55 | ```json 56 | { 57 | "jsonrpc": "2.0", 58 | "id": 1, 59 | "method": "sampling/createMessage", 60 | "params": { 61 | "messages": [ 62 | { 63 | "role": "user", 64 | "content": { 65 | "type": "text", 66 | "text": "What is the capital of France?" 67 | } 68 | } 69 | ], 70 | "modelPreferences": { 71 | "hints": [ 72 | { 73 | "name": "claude-3-sonnet" 74 | } 75 | ], 76 | "intelligencePriority": 0.8, 77 | "speedPriority": 0.5 78 | }, 79 | "systemPrompt": "You are a helpful assistant.", 80 | "maxTokens": 100 81 | } 82 | } 83 | ``` 84 | 85 | **Response:** 86 | 87 | ```json 88 | { 89 | "jsonrpc": "2.0", 90 | "id": 1, 91 | "result": { 92 | "role": "assistant", 93 | "content": { 94 | "type": "text", 95 | "text": "The capital of France is Paris." 96 | }, 97 | "model": "claude-3-sonnet-20240307", 98 | "stopReason": "endTurn" 99 | } 100 | } 101 | ``` 102 | 103 | ## Message Flow 104 | 105 | ```mermaid 106 | sequenceDiagram 107 | participant Server 108 | participant Client 109 | participant User 110 | participant LLM 111 | 112 | Note over Server,Client: Server initiates sampling 113 | Server->>Client: sampling/createMessage 114 | 115 | Note over Client,User: Human-in-the-loop review 116 | Client->>User: Present request for approval 117 | User-->>Client: Review and approve/modify 118 | 119 | Note over Client,LLM: Model interaction 120 | Client->>LLM: Forward approved request 121 | LLM-->>Client: Return generation 122 | 123 | Note over Client,User: Response review 124 | Client->>User: Present response for approval 125 | User-->>Client: Review and approve/modify 126 | 127 | Note over Server,Client: Complete request 128 | Client-->>Server: Return approved response 129 | ``` 130 | 131 | ## Data Types 132 | 133 | ### Messages 134 | 135 | Sampling messages can contain: 136 | 137 | #### Text Content 138 | 139 | ```json 140 | { 141 | "type": "text", 142 | "text": "The message content" 143 | } 144 | ``` 145 | 146 | #### Image Content 147 | 148 | ```json 149 | { 150 | "type": "image", 151 | "data": "base64-encoded-image-data", 152 | "mimeType": "image/jpeg" 153 | } 154 | ``` 155 | 156 | #### Audio Content 157 | 158 | ```json 159 | { 160 | "type": "audio", 161 | "data": "base64-encoded-audio-data", 162 | "mimeType": "audio/wav" 163 | } 164 | ``` 165 | 166 | ### Model Preferences 167 | 168 | Model selection in MCP requires careful abstraction since servers and clients may use 169 | different AI providers with distinct model offerings. A server cannot simply request a 170 | specific model by name since the client may not have access to that exact model or may 171 | prefer to use a different provider's equivalent model. 172 | 173 | To solve this, MCP implements a preference system that combines abstract capability 174 | priorities with optional model hints: 175 | 176 | #### Capability Priorities 177 | 178 | Servers express their needs through three normalized priority values (0-1): 179 | 180 | - `costPriority`: How important is minimizing costs? Higher values prefer cheaper models. 181 | - `speedPriority`: How important is low latency? Higher values prefer faster models. 182 | - `intelligencePriority`: How important are advanced capabilities? Higher values prefer 183 | more capable models. 184 | 185 | #### Model Hints 186 | 187 | While priorities help select models based on characteristics, `hints` allow servers to 188 | suggest specific models or model families: 189 | 190 | - Hints are treated as substrings that can match model names flexibly 191 | - Multiple hints are evaluated in order of preference 192 | - Clients **MAY** map hints to equivalent models from different providers 193 | - Hints are advisory—clients make final model selection 194 | 195 | For example: 196 | 197 | ```json 198 | { 199 | "hints": [ 200 | { "name": "claude-3-sonnet" }, // Prefer Sonnet-class models 201 | { "name": "claude" } // Fall back to any Claude model 202 | ], 203 | "costPriority": 0.3, // Cost is less important 204 | "speedPriority": 0.8, // Speed is very important 205 | "intelligencePriority": 0.5 // Moderate capability needs 206 | } 207 | ``` 208 | 209 | The client processes these preferences to select an appropriate model from its available 210 | options. For instance, if the client doesn't have access to Claude models but has Gemini, 211 | it might map the sonnet hint to `gemini-1.5-pro` based on similar capabilities. 212 | 213 | ## Error Handling 214 | 215 | Clients **SHOULD** return errors for common failure cases: 216 | 217 | Example error: 218 | 219 | ```json 220 | { 221 | "jsonrpc": "2.0", 222 | "id": 1, 223 | "error": { 224 | "code": -1, 225 | "message": "User rejected sampling request" 226 | } 227 | } 228 | ``` 229 | 230 | ## Security Considerations 231 | 232 | 1. Clients **SHOULD** implement user approval controls 233 | 2. Both parties **SHOULD** validate message content 234 | 3. Clients **SHOULD** respect model preference hints 235 | 4. Clients **SHOULD** implement rate limiting 236 | 5. Both parties **MUST** handle sensitive data appropriately 237 | -------------------------------------------------------------------------------- /docs/specification/draft/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Specification 3 | --- 4 | 5 | [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that 6 | enables seamless integration between LLM applications and external data sources and 7 | tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating 8 | custom AI workflows, MCP provides a standardized way to connect LLMs with the context 9 | they need. 10 | 11 | This specification defines the authoritative protocol requirements, based on the 12 | TypeScript schema in 13 | [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.ts). 14 | 15 | For implementation guides and examples, visit 16 | [modelcontextprotocol.io](https://modelcontextprotocol.io). 17 | 18 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 19 | NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 20 | interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) 21 | [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)] 22 | [[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)] when, and only when, they 23 | appear in all capitals, as shown here. 24 | 25 | ## Overview 26 | 27 | MCP provides a standardized way for applications to: 28 | 29 | - Share contextual information with language models 30 | - Expose tools and capabilities to AI systems 31 | - Build composable integrations and workflows 32 | 33 | The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish 34 | communication between: 35 | 36 | - **Hosts**: LLM applications that initiate connections 37 | - **Clients**: Connectors within the host application 38 | - **Servers**: Services that provide context and capabilities 39 | 40 | MCP takes some inspiration from the 41 | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which 42 | standardizes how to add support for programming languages across a whole ecosystem of 43 | development tools. In a similar way, MCP standardizes how to integrate additional context 44 | and tools into the ecosystem of AI applications. 45 | 46 | ## Key Details 47 | 48 | ### Base Protocol 49 | 50 | - [JSON-RPC](https://www.jsonrpc.org/) message format 51 | - Stateful connections 52 | - Server and client capability negotiation 53 | 54 | ### Features 55 | 56 | Servers offer any of the following features to clients: 57 | 58 | - **Resources**: Context and data, for the user or the AI model to use 59 | - **Prompts**: Templated messages and workflows for users 60 | - **Tools**: Functions for the AI model to execute 61 | 62 | Clients may offer the following features to servers: 63 | 64 | - **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions 65 | - **Elicitation**: Server-initiated requests for additional information from users 66 | 67 | ### Additional Utilities 68 | 69 | - Configuration 70 | - Progress tracking 71 | - Cancellation 72 | - Error reporting 73 | - Logging 74 | 75 | ## Security and Trust & Safety 76 | 77 | The Model Context Protocol enables powerful capabilities through arbitrary data access 78 | and code execution paths. With this power comes important security and trust 79 | considerations that all implementors must carefully address. 80 | 81 | ### Key Principles 82 | 83 | 1. **User Consent and Control** 84 | 85 | - Users must explicitly consent to and understand all data access and operations 86 | - Users must retain control over what data is shared and what actions are taken 87 | - Implementors should provide clear UIs for reviewing and authorizing activities 88 | 89 | 2. **Data Privacy** 90 | 91 | - Hosts must obtain explicit user consent before exposing user data to servers 92 | - Hosts must not transmit resource data elsewhere without user consent 93 | - User data should be protected with appropriate access controls 94 | 95 | 3. **Tool Safety** 96 | 97 | - Tools represent arbitrary code execution and must be treated with appropriate 98 | caution. 99 | - In particular, descriptions of tool behavior such as annotations should be 100 | considered untrusted, unless obtained from a trusted server. 101 | - Hosts must obtain explicit user consent before invoking any tool 102 | - Users should understand what each tool does before authorizing its use 103 | 104 | 4. **LLM Sampling Controls** 105 | - Users must explicitly approve any LLM sampling requests 106 | - Users should control: 107 | - Whether sampling occurs at all 108 | - The actual prompt that will be sent 109 | - What results the server can see 110 | - The protocol intentionally limits server visibility into prompts 111 | 112 | ### Implementation Guidelines 113 | 114 | While MCP itself cannot enforce these security principles at the protocol level, 115 | implementors **SHOULD**: 116 | 117 | 1. Build robust consent and authorization flows into their applications 118 | 2. Provide clear documentation of security implications 119 | 3. Implement appropriate access controls and data protections 120 | 4. Follow security best practices in their integrations 121 | 5. Consider privacy implications in their feature designs 122 | 123 | ## Learn More 124 | 125 | Explore the detailed specification for each protocol component: 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | -------------------------------------------------------------------------------- /docs/specification/draft/server/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overview 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | Servers provide the fundamental building blocks for adding context to language models via 8 | MCP. These primitives enable rich interactions between clients, servers, and language 9 | models: 10 | 11 | - **Prompts**: Pre-defined templates or instructions that guide language model 12 | interactions 13 | - **Resources**: Structured data or content that provides additional context to the model 14 | - **Tools**: Executable functions that allow models to perform actions or retrieve 15 | information 16 | 17 | Each primitive can be summarized in the following control hierarchy: 18 | 19 | | Primitive | Control | Description | Example | 20 | | --------- | ---------------------- | -------------------------------------------------- | ------------------------------- | 21 | | Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options | 22 | | Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history | 23 | | Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing | 24 | 25 | Explore these key primitives in more detail below: 26 | 27 | 28 | 29 | 30 | 31 | 32 | -------------------------------------------------------------------------------- /docs/specification/draft/server/resource-picker.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/specification/draft/server/resource-picker.png -------------------------------------------------------------------------------- /docs/specification/draft/server/slash-command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/f2c991bd4d2d4b8d1ae6919634085966cd0587d2/docs/specification/draft/server/slash-command.png -------------------------------------------------------------------------------- /docs/specification/draft/server/utilities/completion.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Completion 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to offer 8 | argument autocompletion suggestions for prompts and resource URIs. This enables rich, 9 | IDE-like experiences where users receive contextual suggestions while entering argument 10 | values. 11 | 12 | ## User Interaction Model 13 | 14 | Completion in MCP is designed to support interactive user experiences similar to IDE code 15 | completion. 16 | 17 | For example, applications may show completion suggestions in a dropdown or popup menu as 18 | users type, with the ability to filter and select from available options. 19 | 20 | However, implementations are free to expose completion through any interface pattern that 21 | suits their needs—the protocol itself does not mandate any specific user 22 | interaction model. 23 | 24 | ## Capabilities 25 | 26 | Servers that support completions **MUST** declare the `completions` capability: 27 | 28 | ```json 29 | { 30 | "capabilities": { 31 | "completions": {} 32 | } 33 | } 34 | ``` 35 | 36 | ## Protocol Messages 37 | 38 | ### Requesting Completions 39 | 40 | To get completion suggestions, clients send a `completion/complete` request specifying 41 | what is being completed through a reference type: 42 | 43 | **Request:** 44 | 45 | ```json 46 | { 47 | "jsonrpc": "2.0", 48 | "id": 1, 49 | "method": "completion/complete", 50 | "params": { 51 | "ref": { 52 | "type": "ref/prompt", 53 | "name": "code_review" 54 | }, 55 | "argument": { 56 | "name": "language", 57 | "value": "py" 58 | } 59 | } 60 | } 61 | ``` 62 | 63 | **Response:** 64 | 65 | ```json 66 | { 67 | "jsonrpc": "2.0", 68 | "id": 1, 69 | "result": { 70 | "completion": { 71 | "values": ["python", "pytorch", "pyside"], 72 | "total": 10, 73 | "hasMore": true 74 | } 75 | } 76 | } 77 | ``` 78 | 79 | ### Reference Types 80 | 81 | The protocol supports two types of completion references: 82 | 83 | | Type | Description | Example | 84 | | -------------- | --------------------------- | --------------------------------------------------- | 85 | | `ref/prompt` | References a prompt by name | `{"type": "ref/prompt", "name": "code_review"}` | 86 | | `ref/resource` | References a resource URI | `{"type": "ref/resource", "uri": "file:///{path}"}` | 87 | 88 | ### Completion Results 89 | 90 | Servers return an array of completion values ranked by relevance, with: 91 | 92 | - Maximum 100 items per response 93 | - Optional total number of available matches 94 | - Boolean indicating if additional results exist 95 | 96 | ## Message Flow 97 | 98 | ```mermaid 99 | sequenceDiagram 100 | participant Client 101 | participant Server 102 | 103 | Note over Client: User types argument 104 | Client->>Server: completion/complete 105 | Server-->>Client: Completion suggestions 106 | 107 | Note over Client: User continues typing 108 | Client->>Server: completion/complete 109 | Server-->>Client: Refined suggestions 110 | ``` 111 | 112 | ## Data Types 113 | 114 | ### CompleteRequest 115 | 116 | - `ref`: A `PromptReference` or `ResourceReference` 117 | - `argument`: Object containing: 118 | - `name`: Argument name 119 | - `value`: Current value 120 | 121 | ### CompleteResult 122 | 123 | - `completion`: Object containing: 124 | - `values`: Array of suggestions (max 100) 125 | - `total`: Optional total matches 126 | - `hasMore`: Additional results flag 127 | 128 | ## Error Handling 129 | 130 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases: 131 | 132 | - Method not found: `-32601` (Capability not supported) 133 | - Invalid prompt name: `-32602` (Invalid params) 134 | - Missing required arguments: `-32602` (Invalid params) 135 | - Internal errors: `-32603` (Internal error) 136 | 137 | ## Implementation Considerations 138 | 139 | 1. Servers **SHOULD**: 140 | 141 | - Return suggestions sorted by relevance 142 | - Implement fuzzy matching where appropriate 143 | - Rate limit completion requests 144 | - Validate all inputs 145 | 146 | 2. Clients **SHOULD**: 147 | - Debounce rapid completion requests 148 | - Cache completion results where appropriate 149 | - Handle missing or partial results gracefully 150 | 151 | ## Security 152 | 153 | Implementations **MUST**: 154 | 155 | - Validate all completion inputs 156 | - Implement appropriate rate limiting 157 | - Control access to sensitive suggestions 158 | - Prevent completion-based information disclosure 159 | -------------------------------------------------------------------------------- /docs/specification/draft/server/utilities/logging.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Logging 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to send 8 | structured log messages to clients. Clients can control logging verbosity by setting 9 | minimum log levels, with servers sending notifications containing severity levels, 10 | optional logger names, and arbitrary JSON-serializable data. 11 | 12 | ## User Interaction Model 13 | 14 | Implementations are free to expose logging through any interface pattern that suits their 15 | needs—the protocol itself does not mandate any specific user interaction model. 16 | 17 | ## Capabilities 18 | 19 | Servers that emit log message notifications **MUST** declare the `logging` capability: 20 | 21 | ```json 22 | { 23 | "capabilities": { 24 | "logging": {} 25 | } 26 | } 27 | ``` 28 | 29 | ## Log Levels 30 | 31 | The protocol follows the standard syslog severity levels specified in 32 | [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1): 33 | 34 | | Level | Description | Example Use Case | 35 | | --------- | -------------------------------- | -------------------------- | 36 | | debug | Detailed debugging information | Function entry/exit points | 37 | | info | General informational messages | Operation progress updates | 38 | | notice | Normal but significant events | Configuration changes | 39 | | warning | Warning conditions | Deprecated feature usage | 40 | | error | Error conditions | Operation failures | 41 | | critical | Critical conditions | System component failures | 42 | | alert | Action must be taken immediately | Data corruption detected | 43 | | emergency | System is unusable | Complete system failure | 44 | 45 | ## Protocol Messages 46 | 47 | ### Setting Log Level 48 | 49 | To configure the minimum log level, clients **MAY** send a `logging/setLevel` request: 50 | 51 | **Request:** 52 | 53 | ```json 54 | { 55 | "jsonrpc": "2.0", 56 | "id": 1, 57 | "method": "logging/setLevel", 58 | "params": { 59 | "level": "info" 60 | } 61 | } 62 | ``` 63 | 64 | ### Log Message Notifications 65 | 66 | Servers send log messages using `notifications/message` notifications: 67 | 68 | ```json 69 | { 70 | "jsonrpc": "2.0", 71 | "method": "notifications/message", 72 | "params": { 73 | "level": "error", 74 | "logger": "database", 75 | "data": { 76 | "error": "Connection failed", 77 | "details": { 78 | "host": "localhost", 79 | "port": 5432 80 | } 81 | } 82 | } 83 | } 84 | ``` 85 | 86 | ## Message Flow 87 | 88 | ```mermaid 89 | sequenceDiagram 90 | participant Client 91 | participant Server 92 | 93 | Note over Client,Server: Configure Logging 94 | Client->>Server: logging/setLevel (info) 95 | Server-->>Client: Empty Result 96 | 97 | Note over Client,Server: Server Activity 98 | Server--)Client: notifications/message (info) 99 | Server--)Client: notifications/message (warning) 100 | Server--)Client: notifications/message (error) 101 | 102 | Note over Client,Server: Level Change 103 | Client->>Server: logging/setLevel (error) 104 | Server-->>Client: Empty Result 105 | Note over Server: Only sends error level
and above 106 | ``` 107 | 108 | ## Error Handling 109 | 110 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases: 111 | 112 | - Invalid log level: `-32602` (Invalid params) 113 | - Configuration errors: `-32603` (Internal error) 114 | 115 | ## Implementation Considerations 116 | 117 | 1. Servers **SHOULD**: 118 | 119 | - Rate limit log messages 120 | - Include relevant context in data field 121 | - Use consistent logger names 122 | - Remove sensitive information 123 | 124 | 2. Clients **MAY**: 125 | - Present log messages in the UI 126 | - Implement log filtering/search 127 | - Display severity visually 128 | - Persist log messages 129 | 130 | ## Security 131 | 132 | 1. Log messages **MUST NOT** contain: 133 | 134 | - Credentials or secrets 135 | - Personal identifying information 136 | - Internal system details that could aid attacks 137 | 138 | 2. Implementations **SHOULD**: 139 | - Rate limit messages 140 | - Validate all data fields 141 | - Control log access 142 | - Monitor for sensitive content 143 | -------------------------------------------------------------------------------- /docs/specification/draft/server/utilities/pagination.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Pagination 3 | --- 4 | 5 | **Protocol Revision**: draft 6 | 7 | The Model Context Protocol (MCP) supports paginating list operations that may return 8 | large result sets. Pagination allows servers to yield results in smaller chunks rather 9 | than all at once. 10 | 11 | Pagination is especially important when connecting to external services over the 12 | internet, but also useful for local integrations to avoid performance issues with large 13 | data sets. 14 | 15 | ## Pagination Model 16 | 17 | Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages. 18 | 19 | - The **cursor** is an opaque string token, representing a position in the result set 20 | - **Page size** is determined by the server, and clients **MUST NOT** assume a fixed page 21 | size 22 | 23 | ## Response Format 24 | 25 | Pagination starts when the server sends a **response** that includes: 26 | 27 | - The current page of results 28 | - An optional `nextCursor` field if more results exist 29 | 30 | ```json 31 | { 32 | "jsonrpc": "2.0", 33 | "id": "123", 34 | "result": { 35 | "resources": [...], 36 | "nextCursor": "eyJwYWdlIjogM30=" 37 | } 38 | } 39 | ``` 40 | 41 | ## Request Format 42 | 43 | After receiving a cursor, the client can _continue_ paginating by issuing a request 44 | including that cursor: 45 | 46 | ```json 47 | { 48 | "jsonrpc": "2.0", 49 | "method": "resources/list", 50 | "params": { 51 | "cursor": "eyJwYWdlIjogMn0=" 52 | } 53 | } 54 | ``` 55 | 56 | ## Pagination Flow 57 | 58 | ```mermaid 59 | sequenceDiagram 60 | participant Client 61 | participant Server 62 | 63 | Client->>Server: List Request (no cursor) 64 | loop Pagination Loop 65 | Server-->>Client: Page of results + nextCursor 66 | Client->>Server: List Request (with cursor) 67 | end 68 | ``` 69 | 70 | ## Operations Supporting Pagination 71 | 72 | The following MCP operations support pagination: 73 | 74 | - `resources/list` - List available resources 75 | - `resources/templates/list` - List resource templates 76 | - `prompts/list` - List available prompts 77 | - `tools/list` - List available tools 78 | 79 | ## Implementation Guidelines 80 | 81 | 1. Servers **SHOULD**: 82 | 83 | - Provide stable cursors 84 | - Handle invalid cursors gracefully 85 | 86 | 2. Clients **SHOULD**: 87 | 88 | - Treat a missing `nextCursor` as the end of results 89 | - Support both paginated and non-paginated flows 90 | 91 | 3. Clients **MUST** treat cursors as opaque tokens: 92 | - Don't make assumptions about cursor format 93 | - Don't attempt to parse or modify cursors 94 | - Don't persist cursors across sessions 95 | 96 | ## Error Handling 97 | 98 | Invalid cursors **SHOULD** result in an error with code -32602 (Invalid params). 99 | -------------------------------------------------------------------------------- /docs/specification/versioning.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Versioning 3 | type: docs 4 | weight: 10 5 | --- 6 | 7 | The Model Context Protocol uses string-based version identifiers following the format 8 | `YYYY-MM-DD`, to indicate the last date backwards incompatible changes were made. 9 | 10 | The protocol version will _not_ be incremented when the 11 | protocol is updated, as long as the changes maintain backwards compatibility. This allows 12 | for incremental improvements while preserving interoperability. 13 | 14 | ## Revisions 15 | 16 | Revisions may be marked as: 17 | 18 | - **Draft**: in-progress specifications, not yet ready for consumption. 19 | - **Current**: the current protocol version, which is ready for use and may continue to 20 | receive backwards compatible changes. 21 | - **Final**: past, complete specifications that will not be changed. 22 | 23 | The **current** protocol version is [**2025-03-26**](/specification/2025-03-26/). 24 | 25 | ## Negotiation 26 | 27 | Version negotiation happens during 28 | [initialization](/specification/2025-03-26/basic/lifecycle#initialization). Clients and 29 | servers **MAY** support multiple protocol versions simultaneously, but they **MUST** 30 | agree on a single version to use for the session. 31 | 32 | The protocol provides appropriate error handling if version negotiation fails, allowing 33 | clients to gracefully terminate connections when they cannot find a version compatible 34 | with the server. 35 | -------------------------------------------------------------------------------- /docs/style.css: -------------------------------------------------------------------------------- 1 | 2 | #feature-support-matrix-wrapper { 3 | overflow-x: auto; 4 | } 5 | 6 | #feature-support-matrix-wrapper table { 7 | min-width: 800px; 8 | } 9 | -------------------------------------------------------------------------------- /docs/tutorials/building-mcp-with-llms.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Building MCP with LLMs" 3 | description: "Speed up your MCP development using LLMs such as Claude!" 4 | --- 5 | 6 | This guide will help you use LLMs to help you build custom Model Context Protocol (MCP) servers and clients. We'll be focusing on Claude for this tutorial, but you can do this with any frontier LLM. 7 | 8 | ## Preparing the documentation 9 | 10 | Before starting, gather the necessary documentation to help Claude understand MCP: 11 | 12 | 1. Visit https://modelcontextprotocol.io/llms-full.txt and copy the full documentation text 13 | 2. Navigate to either the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) or [Python SDK repository](https://github.com/modelcontextprotocol/python-sdk) 14 | 3. Copy the README files and other relevant documentation 15 | 4. Paste these documents into your conversation with Claude 16 | 17 | ## Describing your server 18 | 19 | Once you've provided the documentation, clearly describe to Claude what kind of server you want to build. Be specific about: 20 | 21 | - What resources your server will expose 22 | - What tools it will provide 23 | - Any prompts it should offer 24 | - What external systems it needs to interact with 25 | 26 | For example: 27 | ``` 28 | Build an MCP server that: 29 | - Connects to my company's PostgreSQL database 30 | - Exposes table schemas as resources 31 | - Provides tools for running read-only SQL queries 32 | - Includes prompts for common data analysis tasks 33 | ``` 34 | 35 | ## Working with Claude 36 | 37 | When working with Claude on MCP servers: 38 | 39 | 1. Start with the core functionality first, then iterate to add more features 40 | 2. Ask Claude to explain any parts of the code you don't understand 41 | 3. Request modifications or improvements as needed 42 | 4. Have Claude help you test the server and handle edge cases 43 | 44 | Claude can help implement all the key MCP features: 45 | 46 | - Resource management and exposure 47 | - Tool definitions and implementations 48 | - Prompt templates and handlers 49 | - Error handling and logging 50 | - Connection and transport setup 51 | 52 | ## Best practices 53 | 54 | When building MCP servers with Claude: 55 | 56 | - Break down complex servers into smaller pieces 57 | - Test each component thoroughly before moving on 58 | - Keep security in mind - validate inputs and limit access appropriately 59 | - Document your code well for future maintenance 60 | - Follow MCP protocol specifications carefully 61 | 62 | ## Next steps 63 | 64 | After Claude helps you build your server: 65 | 66 | 1. Review the generated code carefully 67 | 2. Test the server with the MCP Inspector tool 68 | 3. Connect it to Claude.app or other MCP clients 69 | 4. Iterate based on real usage and feedback 70 | 71 | Remember that Claude can help you modify and improve your server as requirements change over time. 72 | 73 | Need more guidance? Just ask Claude specific questions about implementing MCP features or troubleshooting issues that arise. -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@modelcontextprotocol/specification", 3 | "private": true, 4 | "version": "0.1.0", 5 | "description": "Model Context Protocol specification and protocol schema", 6 | "license": "MIT", 7 | "author": "Anthropic, PBC (https://anthropic.com)", 8 | "homepage": "https://modelcontextprotocol.io", 9 | "bugs": "https://github.com/modelcontextprotocol/specification/issues", 10 | "engines": { 11 | "node": ">=20" 12 | }, 13 | "prettier": { 14 | "overrides": [ 15 | { 16 | "files": "*.md", 17 | "options": { 18 | "printWidth": 89, 19 | "proseWrap": "always" 20 | } 21 | } 22 | ] 23 | }, 24 | "scripts": { 25 | "validate:schema": "tsc", 26 | "generate:json": "for f in schema/*/schema.ts; do typescript-json-schema --defaultNumberType integer --required --skipLibCheck \"$f\" \"*\" -o \"${f%ts}json\"; done", 27 | "serve:docs": "cd docs && mintlify dev", 28 | "format": "prettier --write \"**/*.md\"", 29 | "format:check": "prettier --check \"**/*.md\"" 30 | }, 31 | "devDependencies": { 32 | "ajv": "^8.17.1", 33 | "ajv-formats": "^3.0.1", 34 | "glob": "^11.0.0", 35 | "mintlify": "^4.0.468", 36 | "prettier": "^3.4.2", 37 | "tsx": "^4.19.1", 38 | "typescript": "^5.6.2", 39 | "typescript-json-schema": "^0.65.1" 40 | }, 41 | "resolutions": { 42 | "fast-json-patch": "^3.1.1" 43 | } 44 | } 45 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "noEmit": true, 4 | "target": "es2016", 5 | "rootDir": "schema", 6 | "forceConsistentCasingInFileNames": true, 7 | "strict": true, 8 | "skipLibCheck": true 9 | } 10 | } 11 | --------------------------------------------------------------------------------