Create a MCP Server for Claude Code — a practical, up-to-step guide

The Model Context Protocol (MCP) is an open standard that lets models like Anthropic’s Claude and developer tools like Claude Code call out to external tools, data sources and prompts in a safe, standard way.

This guide will walk you through building your own MCP server from scratch, enabling Claude Code to access custom features and thus greatly extend its functionality far beyond its built-in features.

What is the Model Context Protocol (MCP)?

MCP (Model Context Protocol) is an open specification designed to standardize how language-model clients (like Claude, Claude Code, or other LLM frontends) connect to tool servers and data sources. Think of MCP as a “USB-C port for LLMs”: it defines a transport/JSON-RPC schema and a common way for servers to publish three kinds of capabilities:

• Resources — file-like or document data that a client can read (e.g., a database row, a text file, a JSON payload).
• Tools — callable functions that the model can ask the host to execute (with user approval).
• Prompts — reusable prompt templates or workflows the model/client can invoke.

MCP supports multiple transports (stdio, HTTP, SSE) and provides schema, SDKs and example servers so you don’t have to invent the wire format yourself. The protocol is maintained publicly (spec + SDKs) and has tutorials and a gallery of example servers to accelerate adoption.

How is MCP architected?

MCP’s architecture is intentionally simple and modular: the core pieces are MCP servers, MCP clients, and transports that carry JSON-RPC framed messages between them. Below are the principal components you’ll interact with when building a server for Claude Code (or other MCP clients).

Server, client and the protocol

• MCP server — A service that publishes tools, resources and prompts. Tools can perform side-effects or fetch data; resources surface read-only content; prompts are reusable prompt templates the client can ask the model to sample from.
• MCP client (host) — Typically part of the LLM host (e.g., Claude Code, VS Code plugin, a browser client). It discovers available servers, presents tool descriptions to the model, and routes model-initiated calls to servers.
• Protocol — Messages are encoded as JSON-RPC; the spec defines lifecycle events, tool discovery, invocation, completions/sampling, and how structured results are transported back to the client and model.

Communication pattern (what happens when a tool is used)

1. Client sends user message to the model.
2. Model analyzes context and decides to call a tool exposed by MCP (or multiple tools).
3. Client forwards the tool call to the MCP server over the chosen transport.
4. Server executes the tool and returns results.
5. Model receives tool output and composes the final answer to the user. ([Model Context Protocol][1])

Implementation primitives

• JSON-RPC messages follow the MCP schema.
• Tool definitions are published in the server’s discovery responses so clients can present them in the UI.
• Resources are referenced by @source:path syntax by clients (e.g., @postgres:...), letting models refer to external content without inlining huge data into the prompt.

Why integrate Claude Code with MCP servers?

Claude Code is Anthropic’s offering focused on code- and developer-centric workflows (editor/IDE integration, code understanding, etc.). Exposing your internal tools (source search, CI runner, ticket system, private registries) through MCP servers lets Claude Code call them as first-class tools inside coding conversations and agent flows.

Integrating Claude Code with MCP servers unlocks practical, production-relevant capabilities for a coding agent:

1. Let the model act on real systems

Claude Code can ask an MCP server to query issue trackers, run database queries, read large docs, or produce GitHub PRs — enabling end-to-end automation from within the coding session. This is explicitly supported by Claude Code docs (examples: querying Postgres, Sentry, or creating PRs).

2. Offload large data and specialized logic

Instead of embedding every data source into the prompt (which consumes tokens), you publish data and tools through MCP. The model calls the tool, gets a structured response, and reasons with it — this reduces token usage and lets servers handle heavy work (DB queries, long file reads, auth).

3. Security and governance

MCP centralizes access control and auditing at the server layer, letting organizations whitelist approved servers, control what tools are available, and limit outputs. Claude Code also supports enterprise MCP configuration and per-scope consent.

4. Reusability and ecosystem

MCP servers are reusable across clients and teams. Build once and many Claude/LLM clients can use the same services (or swap implementations).

What do you need before you start?

Minimum requirements

• A development machine with Python 3.10+ (we’ll use Python in the example). Alternatively Node / other languages are supported by MCP SDKs.
• uv (Astral’s tool) or equivalent runner for running MCP stdio servers (the MCP tutorial uses uv). Installation steps shown below.
• Claude Code installed or access to Claude client (desktop or CLI) to register and test your server; or any MCP-capable client. Claude Code supports HTTP, SSE and local stdio servers.
• Security note: Only add trusted MCP servers to Claude Code in team or enterprise settings — MCP gives servers access to sensitive data, and prompt injection risks exist if a server returns malicious content.

How to install and verify the Claude Code CLI

This is Claude Code Installation and Usage Guide.

1) Quick summary — recommended install methods

Use the native installer (recommended) or Homebrew on macOS/Linux. NPM is available if you need a Node-based install. Windows gets PowerShell / CMD installers. Source: official Claude Code docs & GitHub.

2) Prerequisites

• macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (WSL recommended on Windows).
• Node.js 18+ only required for the NPM install method.

3) Installation commands (pick one)

Native (recommended — no Node dependency)，macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash
# optional: install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest
# or install a specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex
# or for latest: & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

(These are the official native installer scripts).

NPM (if you want a Node-based global install)：

# requires Node.js 18+
npm install -g @anthropic-ai/claude-code

Do not use sudo npm install -g — warn against sudo global installs (permission/security issues). If you hit permission errors, use nvm or fix your npm global prefix rather than using sudo.

4) Verify the binary was installed (basic checks)

Run these locally immediately after installation:

# is the command on PATH?
which claude

# version (or -v)
claude --version
# or
claude -v

# help (sanity check)
claude --help

Expected: which shows a path (e.g. /usr/local/bin/claude or ~/.nvm/.../bin/claude) and claude --version prints a semver-like string. The docs and README both show claude as the primary CLI entrypoint.

5) Verify install health and configuration (recommended checks)

a) claude doctor，Run:

claude doctor

This built-in diagnostic checks your install type, common problems (like npm permission issues), dependencies such as ripgrep, and suggests fixes. The docs explicitly recommend running claude doctor after install.

b) Run a smoke test (non-interactive)

From your project directory:

cd /path/to/your/project
claude -p "Explain this project in 3 sentences"

This uses print mode (-p) to send a single prompt then exit; good for CI or quick functional checks.

c) Authentication verification (make sure the CLI can reach Anthropic)

Claude Code supports several auth flows (Console OAuth, API key, provider integrations). Common checks:

1. If using an API key (CI / headless / local env var):

export ANTHROPIC_API_KEY="sk-..."
# then
claude auth status
claude auth whoami    # or `claude auth whoami` / `claude whoami` depending on version

You can use CometAPI‘s API key to use Claude Code, Using Claude’s API through CometAPI will give you a 20% discount.

2. If you used OAuth via the console — run:

claude auth status
claude auth whoami

You should see account/plan info or a confirmation that you’re authenticated.