What is MCP?
Model Context Protocol (MCP) lets Claude access external services in a safe, standardized way. Build the server once and it works in Claude Code, Claude Desktop, and other MCP-compatible IDEs.
Pick a transport
| Transport | Good for | Auth |
|---|---|---|
| HTTP (Streamable HTTP) | Remote SaaS, multi-user | OAuth, API keys |
| stdio | Local CLI tools, system access | Env vars, tokens |
| SSE | Deprecated; some legacy remote servers | OAuth |
The current MCP specification (2026-07-28) defines two standard transports: stdio and Streamable HTTP. New remote servers should use HTTP. On Claude Code v2.1.265 or later, a server added with --transport http switches to SSE automatically when it doesn’t accept HTTP.
Prerequisites
- Node.js 20 or later (TypeScript SDK v2), or Python 3.11+ (Python SDK v2)
- Claude Code installed
- A service or data source to expose
Initialize (TypeScript example)
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zod tsx
mkdir src
type=module matters because the SDK ships ES modules only. tsx runs TypeScript directly, so there is no build step.
v2 of the TypeScript SDK (@modelcontextprotocol/server) is the stable release line, released 2026-07-27, and implements the 2026-07-28 MCP spec. v1 (@modelcontextprotocol/sdk) still works, but it lives on the v1.x branch and receives only bug fixes and security updates, for at least six months after the v2 release.
Server building blocks
An MCP server has three primitives:
- Tools — functions Claude can call
- Resources — data Claude can read (files, DB rows, etc.)
- Prompts — predefined prompt templates
Most servers only need Tools.
Define a Tool (weather example)
src/index.ts:
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";
function createServer(): McpServer {
const server = new McpServer({ name: "weather-server", version: "1.0.0" });
server.registerTool(
"get-weather",
{
description: "Returns current weather for a city",
inputSchema: z.object({
city: z.string().describe("City name in English"),
}),
},
async ({ city }) => {
const weather = await fetchWeather(city); // your weather API call
return {
content: [{ type: "text", text: JSON.stringify(weather, null, 2) }],
};
}
);
return server;
}
inputSchema is a Zod schema (z.object(...)). From that one schema the SDK derives the JSON Schema the model sees and validates arguments before your handler runs.
The description is the key signal Claude uses to decide when to call the tool. Make it specific.
Run on stdio transport
At the end of the file, hand the factory to serveStdio:
void serveStdio(createServer);
console.error("weather MCP server running on stdio");
Run it:
npx tsx src/index.ts
stdout is the protocol channel. Log with console.error; one console.log corrupts the JSON-RPC stream.
Claude Code sets CLAUDE_PROJECT_DIR in the spawned server’s environment to the project root, so your server can resolve project-relative paths with process.env.CLAUDE_PROJECT_DIR.
To call your tools without a host, use the MCP Inspector:
npx @modelcontextprotocol/inspector npx tsx src/index.ts
Build it in Python
Python SDK v2 defines tools with MCPServer and a decorator. The type hints are the schema.
uv add "mcp[cli]" # or: pip install "mcp[cli]"
from mcp.server import MCPServer
mcp = MCPServer("weather-server")
@mcp.tool()
def get_weather(city: str) -> str:
"""Returns current weather for a city."""
return fetch_weather(city) # your weather API call
if __name__ == "__main__":
mcp.run() # with no arguments, starts a stdio server
Connect it to Claude Code. uv run --with resolves the SDK into a fresh environment on the spot, so it works from any directory.
claude mcp add weather-py -- uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py
Connect to Claude Code
1. Local stdio server
Register the server from the project root; everything after -- is the launch command.
claude mcp add weather -- npx tsx src/index.ts
The default scope is local (available only to you in the current project). Add --scope user to make it available across all projects, or --scope project to share with the team via .mcp.json. For user scope, use an absolute path to the server file, since the server may launch from other directories.
2. Remote HTTP server
claude mcp add --transport http weather https://mcp.example.com/mcp
If OAuth is required, run /mcp in Claude Code to authenticate.
3. Share at the project level (.mcp.json)
A .mcp.json at the project root lets your team share MCP config:
{
"mcpServers": {
"weather": {
"type": "http",
"url": "https://mcp.example.com/mcp"
}
}
}
For a remote server that pushes events to Claude unprompted, .mcp.json also accepts "type": "ws" (WebSocket). Authentication is header-only, and WebSocket supports neither OAuth nor the claude mcp add --transport flag.
Connect to Claude Desktop
Claude Desktop loads stdio MCP servers from its own config file. Instead of claude mcp add, you edit the JSON directly.
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Create the file if it doesn’t exist. Desktop launches the server outside your project directory, so use absolute paths.
{
"mcpServers": {
"weather": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/my-mcp-server/src/index.ts"]
}
}
}
A host spawns your server with a minimal PATH, so npx or uv may not be found. Replace the bare command with the absolute path from which npx (macOS/Linux) or where npx (Windows). For a Python server, uv run mcp install server.py writes the entry into Claude Desktop’s config for you.
After saving, fully quit (Cmd+Q) and relaunch the Desktop app — closing the window is not enough. Once it’s back, you can see the exposed tools from the tools panel below the chat input.
Designing permission-sensitive tools
When you expose anything powerful — shell execution, the file system, outbound network — split the surface into narrow tools. Claude Code permission rules match MCP tools by name (mcp__<server>__<tool>), and settings files skip any mcp__ rule that tries to match a parameter. The wider one tool’s input schema is, the more a single allow rule for it grants.
Bad — exposing a generic shell
server.registerTool("run_shell", {
description: "Runs an arbitrary shell command",
inputSchema: z.object({ command: z.string() }),
}, async ({ command }) => { /* ... */ });
This one tool covers everything from ls to rm -rf and curl under the same permission grant. Once it’s allowed, it’s effectively unrestricted shell access.
Good — split by intent
server.registerTool("list_files", {
description: "Lists files in a directory",
inputSchema: z.object({ path: z.string() }),
}, /* ... */);
server.registerTool("read_file", {
description: "Reads a text file",
inputSchema: z.object({ path: z.string() }),
}, /* ... */);
server.registerTool("git_status", {
description: "Returns git status for the current repo",
inputSchema: z.object({}),
}, /* ... */);
Each tool has a constrained input schema, so unintended operations don’t slip through, and users can set different approval policies per tool.
Design principles
- Constrain with the schema, not the prompt — narrow
inputSchemabeats telling the model “don’t do dangerous things” indescription. - Make tools with side effects (writes, executes) visually distinct from read-only ones by name and return value.
- Re-validate path and URL arguments server-side against an allowlist — don’t trust whatever Claude passes in.
Test
claude
/mcp
The added server’s status and exposed tools show up. Then ask Claude in plain language to call the tool and confirm the result.
Distribution patterns
- SaaS — host an HTTP MCP server at your domain (e.g.
https://mcp.notion.com/mcp) with OAuth login. - Personal tool — publish as an npm package; document
claude mcp addin the README. - Bundle in a plugin — include the MCP server in a plugin and distribute it through a marketplace, so installing the plugin brings the server with it.
Next steps
- Read the implementations of Notion MCP, GitHub MCP, and Slack MCP for patterns.
- See the TypeScript SDK v2 docs and Python SDK docs for Resources, Prompts, OAuth, and more.
- See the Claude Code MCP docs for scopes, authentication, and output limits.
- Token usage and latency matter — keep tool responses short and return structured JSON.