Documentation Index

Fetch the complete documentation index at: https://modelcontextprotocol.io/llms.txt Use this file to discover all available pages before exploring further.

Contributing to MCP

How to contribute to the Model Context Protocol project

The Model Context Protocol (MCP) is an open source project that welcomes contributions from the community. This guide walks you through everything you need to get started.

Before You Begin

Prerequisites

Before contributing, ensure you have the following installed and ready:

• Git - For cloning repositories and submitting changes
• Node.js 24+ - Required for building and testing our projects
• npm - Comes with Node.js, used for dependency management
• GitHub account - For submitting pull requests and issues
• Language-specific tooling - If contributing to an SDK, you’ll need the appropriate development environment for that language (e.g., Python, Rust, Go)

Verify your setup:

node --version  # Should be 24.x or higher
npm --version   # Should be 11.x or higher
git --version   # Any recent version

<Note> These commands work the same on macOS, Linux, and Windows, so you’re good to go on any platform.

Repository Structure

MCP spans multiple repositories in the modelcontextprotocol organization on GitHub. Here are a few notable sub-projects worth checking out:

Throughout this guide, specification repository refers to modelcontextprotocol/modelcontextprotocol, which contains the protocol spec, this documentation site, and Spec Enhancement Proposals (SEPs).

Project Roles

MCP follows a governance model with different levels of responsibility:

• Contributors - Anyone who files issues, submits PRs, or participates in discussions (that’s you!)
• Maintainers - Steward specific areas like SDKs, documentation, or Working Groups
• Core Maintainers - Guide overall project direction, review SEPs, and oversee the specification

You can find the current list of maintainers in the MAINTAINERS.md file.

Maintainers are here to help you succeed! Don’t hesitate to reach out if you have questions or need guidance on your contribution.

Your First Contribution

Start here if you are new to MCP and contributing to its ecosystem.

<Note> While we use the specification repository as an example, the key patterns are applicable to other MCP repos as well.

Step 1: Set Up Your Environment

Set up your local environment so you can test and validate changes before submitting them.

<Steps> Click the Fork button on the repository page to create your own copy. This gives you a personal workspace where you can make changes without affecting the main project.

Replace `YOUR-USERNAME` with your GitHub username.

This installs the tools needed for schema generation, documentation building, and validation.

This runs TypeScript compilation, schema validation, example validation, documentation link checks, and formatting checks. If everything passes, your environment is good and you're ready to contribute.

If npm run check fails, see Troubleshooting below.

Step 2: Find Something to Work On

While a lot of the items you might see tracked in the repository can feel intimidating, especially for newcomers, there are plenty of places where you can start with your first improvements:

1. Documentation improvements - Help us fix typos, unclear explanations, broken links, or incomplete examples
2. Issues labeled good first issue - Tackle issues tagged in the specification repo as well as our SDK repos
3. Schema examples - Add examples to schema/draft/examples/ to make it easier for developers to understand protocol primitives

Step 3: Make Your Change

Create your changes in a dedicated branch.

<Steps> bash theme={null} git checkout -b fix/your-description

Use a descriptive branch name that reflects your change, like `fix/typo-in-tools-doc` or `feat/add-example-for-resources`.

Fix any issues before committing. If you have formatting errors, `npm run format` can auto-fix most of them.

Write a concise message that describes what you changed and why. Reference issue numbers if applicable (e.g., `Fix typo in tools documentation (#123)`).

Step 4: Submit a Pull Request

When you’re ready, push your branch and open a pull request.

<Steps> bash theme={null} git push origin fix/your-description

```bash theme={null}
gh pr create --fill
```

Alternatively, navigate to your fork on GitHub and click **Compare & pull request**.

<Tip> That’s it, congratulations on your first contribution! Every improvement, no matter how small, helps make MCP better for everyone.

What Makes a Good Contribution

Help us review your contribution quickly by following these patterns:

Types of Contributions

Different contributions follow different processes depending on their scope.

<Tip> Not sure which category your change falls into? Ask in the MCP Contributor Discord before starting any significant work.

Small Changes (Direct PR)

Simply submit a pull request directly to the repo for:

• Bug fixes and typo corrections
• Documentation improvements, such as bringing clarity to an ambiguous or unclear section
• Adding examples to existing features
• Minor schema fixes that don’t materially change the specification or SDK behavior
• Test improvements

Major Changes (SEP Required)

Anything that changes the MCP specification requires following the Specification Enhancement Proposal (SEP) process. This includes, but is not limited to:

• New protocol features or API methods
• Breaking changes to existing behavior
• Changes to the message format or schema structure
• New interoperability standards
• Governance or process changes

Here are a few concrete examples of what would require following the SEP steps:

• Adding a new RPC method like tools/execute
• Changing how authentication and authorization works
• Adding a new capability negotiation field
• Modifying the transport layer specification

Working with the Specification Repository

Once you’ve determined what type of contribution you’re making, here’s how to work with the specification repository.

Schema Changes

The TypeScript schema (schema/draft/schema.ts) is the source of truth for the protocol. It defines every message type, request/response structure, and primitive (tools, resources, prompts) that clients and servers exchange. SDK implementers across all languages rely on this schema to build conformant implementations.

When you run npm run generate:schema, it generates:

• The JSON schema (schema/draft/schema.json) for validation
• The Schema Reference documentation (docs/specification/draft/schema.mdx)

To modify the schema:

<Steps> Make your changes in schema/draft/schema.ts.

Documentation Changes

Docs are written in MDX format (Markdown with JSX components) and powered by Mintlify. The docs/ directory contains:

• docs/docs/ - Guides and tutorials for getting started and building with MCP
• docs/specification/ - Formal protocol specification (versioned by date)

Here is how you can contribute to our documentation:

<Steps> bash theme={null} npm run serve:docs

This launches a live preview at `http://localhost:3000` with hot reloading.

This validates formatting, broken links, and other common issues.

Major Protocol Changes

For significant changes, follow the SEP process. Prior to spending a lot of time on a spec proposal, make sure to follow these best practices.

<Steps> Discuss in an Interest Group or on Discord.

Working with the SDK Repositories

MCP maintains official SDKs in multiple languages. Contributions are welcome - whether you’re fixing bugs, improving performance, adding features, or enhancing documentation.

<Note> Each SDK has its own repository, maintainers, and contribution guidelines. Some SDKs are maintained in collaboration with larger partner organizations, such as Google, Microsoft, JetBrains, and others, so processes may vary slightly between repositories.

Before Contributing to an SDK

Before diving into code, follow these steps.

<Steps> Before starting significant work, open an issue to discuss your approach. This helps avoid duplicate effort, ensures your contribution aligns with the SDK’s direction, and gives maintainers a chance to provide early feedback.

SDK Repositories

Getting Help

Communication Channels

Got questions or need guidance? The MCP community is here to help.

• Discord - Real-time discussion with contributors and maintainers, focused on MCP contributions (not general MCP support)
• GitHub Discussions - Exploration and conversation: feature requests, questions, roadmap planning, and proposals that need input before becoming concrete tasks
• GitHub Issues - Actionable work: bug reports with reproducible steps, documentation fixes, and tasks that are well-defined and ready to implement (not feature requests)

This separation helps maintainers focus on work that’s ready for implementation while giving ideas room to develop. If you’re unsure whether something is ready to be an issue, start with a discussion. For a complete guide, see our Contributor Communication documentation.

For protocol discussions, join Working Group channels like #auth-wg or #server-identity-wg. For SDK help, find your language’s channel (e.g., #typescript-sdk-dev).

Finding a Sponsor for SEPs

A sponsor is a Core Maintainer or Maintainer who champions your SEP through the review process. They provide feedback, help refine your proposal, and present it at Core Maintainer meetings.

<Warning> Every SEP needs a sponsor to move forward. SEPs that don’t find a sponsor within 6 months are marked as dormant. Dormant SEPs aren’t rejected outright - they can be revived later if a sponsor is found or the proposal is re-assessed to be needed.

To find a sponsor:

<Steps> Look at the maintainer list to find maintainers working in your area.

Maintainers review open proposals regularly, but response time varies based on complexity and availability.

Troubleshooting

Sometimes things don’t go as planned - that’s completely normal! Here are solutions to common issues. If you’re still stuck, don’t hesitate to ask for help in Discord. The community is friendly and happy to help you get unstuck.

npm run check fails

Common causes:

• Wrong Node.js version - Ensure you have Node.js 24+
• Missing dependencies - Run npm install again
• Schema out of sync - Run npm run generate:schema
• Formatting issues - Run npm run format to auto-fix

My PR has been sitting unnoticed for weeks

1. Ensure all CI checks pass
2. Politely ping the desired reviewer in a comment
3. Ask in the relevant Discord channel
4. For urgent issues, reach out to a Core Maintainer

I can’t find a sponsor for my SEP

1. Make sure your idea has been discussed in Discord or an Interest Group first
2. Proposals with demonstrated community interest are more likely to find sponsors
3. Consider whether your change might be too large - could it be split into smaller SEPs?

My SEP was rejected

Don’t take it personally - a SEP rejection doesn’t mean your idea was bad. SEPs can be rejected for many reasons: timing, scope, competing priorities, or simply because the protocol isn’t ready for that change yet. The feedback you receive is valuable and often points toward a path forward.

Rejection is not permanent. You have a few options ahead:

1. Address the feedback and resubmit - Often, rejection comes with specific concerns. Addressing those concerns and resubmitting can be the right path forward.
2. Discuss in Discord - Talk with maintainers to better understand the concerns. Sometimes a brief conversation reveals a simpler path forward.
3. Try a different approach - Submit a new SEP that addresses the same problem differently, incorporating what you learned.
4. Wait for the right moment - Circumstances change. New use cases emerge, the community grows, and priorities shift. An idea rejected today might be welcomed tomorrow.

Out of Scope

This guide covers contributions to the core MCP project - the specification, official SDKs, and documentation.

Building your own MCP servers, clients, or tools is not covered here. For guidance on building with MCP, see our documentation:

• Build a Server
• Build a Client
• Example Servers

If you build something you’d like to share with the community, you can submit it to the MCP Registry.

AI Contributions

We welcome the use of AI tools like Claude or ChatGPT to help with your contributions! If you do use AI assistance, just let us know in your pull request or issue - a quick note about how you used it (drafting docs, generating code, brainstorming, etc.) is all we need.

The key is that you understand and can stand behind your contribution:

• You get it - You understand what the changes do and can explain them
• You know why - You can articulate why the change is needed
• You’ve verified it - You’ve tested or validated that it works as intended

You can read the full policy in AI_POLICY.md.

Code of Conduct

All contributors must follow the Code of Conduct. We expect respectful, professional, and inclusive interactions across all channels.

License

By contributing, you agree that your contributions will be licensed under:

• Code and specifications: Apache License 2.0
• Documentation (excluding specifications): CC-BY 4.0

See the LICENSE file for details.

Last updated Oct 08, 2026