MCP Python SDK vs MCP TypeScript SDK

MCP Python SDK

Documentation

The documentation lives at https://py.sdk.modelcontextprotocol.io/.

It has a Get started guide, What's new in v2, the API reference, and the migration guide.

What is MCP?

The Model Context Protocol lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but designed for LLM interactions. With this SDK you can:

• Build MCP servers that expose tools, resources, and prompts to any MCP host
• Build MCP clients that connect to any MCP server
• Speak every standard transport: stdio, Streamable HTTP, and SSE

Requirements

Python 3.11+.

Installation

uv add "mcp[cli]"      # or: pip install "mcp[cli]"

The cli extra adds the mcp command-line tool (mcp dev, mcp run, mcp install) on top of the SDK; install plain mcp if you don't need it. For one-off commands, uv run --with "mcp[cli]" mcp ... works without a project.

A server in 15 lines

Create a server.py:

from mcp.server import MCPServer

mcp = MCPServer("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

Full example: docs_src/index/tutorial001.py

That's a complete MCP server: one tool, one templated resource. Open it in the MCP Inspector:

uv run mcp dev server.py

Call add with a=1, b=2 and you get 3 back.

Notice what you did not write: no JSON Schema (a: int, b: int is the schema), no request parsing, no validation code, no protocol handling. Two type-hinted Python functions and a docstring.

Get started takes it from here.

A client in 10 lines

The same package is a full MCP client. Serve server.py over HTTP:

uv run mcp run server.py --transport streamable-http

then point a Client at it:

import asyncio

from mcp import Client

async def main() -> None:
    async with Client("http://localhost:8000/mcp") as client:
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(result.structured_content)  # {'result': 3}

asyncio.run(main())

A URL means Streamable HTTP, the transport you deploy. Client can also launch a local server as a stdio subprocess or take any custom transport; Clients has the rest.

Contributing

We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. See the contributing guide to get started.

License

This project is licensed under the MIT License. See the LICENSE file for details.

MCP TypeScript SDK

[!IMPORTANT]
This is the main branch: v2 of the SDK (@modelcontextprotocol/server, @modelcontextprotocol/client), the stable release line, implementing the 2026-07-28 MCP spec. Start with the v2 documentation; coming from v1, see the migration guide.

v1.x (@modelcontextprotocol/sdk) lives on the v1.x branch and continues to receive bug fixes and security updates for at least six months after the v2 release (2026-07-27). Its documentation is at ts.sdk.modelcontextprotocol.io.

Found a problem in v2? Open an issue.

[!NOTE]
Contributors without write access can have one open pull request at a time. Draft pull requests don't count toward the limit. For a feature or a larger change, please open an issue first; see CONTRIBUTING.md.

Overview

The Model Context Protocol (MCP) allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction.

This repository contains the TypeScript SDK implementation of the MCP specification. It runs on Node.js, Bun, and Deno, and ships:

• MCP server libraries (tools/resources/prompts, Streamable HTTP, stdio, auth helpers)
• MCP client libraries (transports, high-level helpers, OAuth helpers)
• Optional middleware packages for specific runtimes/frameworks (Express, Fastify, Hono, Node.js HTTP)
• Runnable examples (under examples/)

Packages

This monorepo publishes split packages:

• @modelcontextprotocol/server: build MCP servers
• @modelcontextprotocol/client: build MCP clients

Tool and prompt schemas use Standard Schema — bring Zod v4, Valibot, ArkType, or any compatible library.

Middleware packages (optional)

The SDK also publishes small "middleware" packages under packages/middleware/ that help you wire MCP into a specific runtime or web framework.

They are intentionally thin adapters: they should not introduce new MCP functionality or business logic. See packages/middleware/README.md for details.

• @modelcontextprotocol/node: Node.js Streamable HTTP transport wrapper for IncomingMessage / ServerResponse
• @modelcontextprotocol/express: Express helpers (app defaults + Host header validation)
• @modelcontextprotocol/fastify: Fastify helpers (app defaults + Host header validation)
• @modelcontextprotocol/hono: Hono helpers (app defaults + JSON body parsing hook + Host header validation)

Installation

Server

npm install @modelcontextprotocol/server
## or
bun add @modelcontextprotocol/server
## or
deno add npm:@modelcontextprotocol/server

Client

npm install @modelcontextprotocol/client
## or
bun add @modelcontextprotocol/client
## or
deno add npm:@modelcontextprotocol/client

Optional middleware packages

The SDK also publishes optional “middleware” packages that help you wire MCP into a specific runtime or web framework (for example Express, Fastify, Hono, or Node.js http).

These packages are intentionally thin adapters and should not introduce additional MCP features or business logic. See packages/middleware/README.md for details.

## Node.js HTTP (IncomingMessage/ServerResponse) Streamable HTTP transport:
npm install @modelcontextprotocol/node

## Express integration:
npm install @modelcontextprotocol/express express

## Fastify integration:
npm install @modelcontextprotocol/fastify fastify

## Hono integration:
npm install @modelcontextprotocol/hono hono

Getting Started

Here is what an MCP server looks like. This minimal example exposes a single greet tool over stdio:

import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

const server = new McpServer({ name: 'greeting-server', version: '1.0.0' });

server.registerTool(
    'greet',
    {
        description: 'Greet someone by name',
        inputSchema: z.object({ name: z.string() })
    },
    async ({ name }) => ({
        content: [{ type: 'text', text: `Hello, ${name}!` }]
    })
);

async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
}

main();

Ready to build something real? Follow the step-by-step tutorials:

• Build your first server — a stdio weather-alert server, from npm init to a tool call
• Build your first client — connect to that server, list its tools, and call them

For runnable, end-to-end examples beyond the tutorials, see:

• examples/README.md — runnable, self-verifying client/server example pairs (one story per directory)

Documentation

• Build a server — your first MCP server, step by step
• Build a client — your first MCP client, step by step
• Documentation site — the full guides: tools, resources, prompts, serving over HTTP and stdio, clients, OAuth, and migration
• Troubleshooting — common errors and their fixes
• API reference
• MCP documentation
• MCP specification

Building docs locally

To work on the documentation site locally:

pnpm docs:api      # Generate the API reference markdown (output: docs/api/)
pnpm docs:dev      # Start the VitePress dev server for the V2 site
pnpm docs:build    # Build the V2 site (output: docs/.vitepress/dist/)
pnpm docs:multi    # Build the combined V1 + V2 site (output: tmp/docs-combined/)

The docs:multi script builds the V2 site from the current checkout, checks out the v1.x branch via a git worktree to build the V1 site, and produces a combined site with V1 docs at the root and V2 docs under /v2/.

v1 (legacy) documentation and fixes

If you are using the v1 generation of the SDK, the v1 API documentation is available at https://ts.sdk.modelcontextprotocol.io/. The v1 source code and any v1-specific fixes live on the long-lived
v1.x branch. V2 API docs are at /v2/.

Contributing

Issues and pull requests are welcome on GitHub at https://github.com/modelcontextprotocol/typescript-sdk.

License

This project is licensed under the Apache License 2.0 for new contributions, with existing code under MIT. See the LICENSE file for details.