MCP servers in Claude Code

The Model Context Protocol (MCP) is how Claude Code gets tools beyond its built-in ones: a server exposes tools, and Claude Code connects to it and lets the model call them. Exercises in the agent and tooling courses ask you to connect existing servers and to write your own. This page covers the commands; the lesson Tools and the agent-computer interface explains the idea.

Before you start

• Claude Code installed and signed in.
• Node.js 24 or newer for the npx-based servers below. The Everything test server needs Node 24.
• Only connect servers you trust. A server's tools run with your permissions, and its output goes into the model's context.

1. Know the two transports

SSE is an older remote transport and is deprecated. Use HTTP where a server offers it.

2. Choose a scope

For exercises, use local for a server you're trying out, project when an answer project ships an .mcp.json, and user for a server you want everywhere.

3. Add and test a stdio server

The reference Everything server exists for testing clients. It has simple tools such as echo and get-sum. From an empty folder:

claude mcp add --transport stdio everything -- npx -y @modelcontextprotocol/server-everything

Everything after -- is the command that starts the server. Claude Code's own options (--transport, --scope, --env) go before the server name.

Pass secrets with --env, and put another option between --env and the name, or the CLI reads the name as one more KEY=value pair:

claude mcp add --env API_TOKEN=your-token --transport stdio my-server -- npx -y some-mcp-server

Native Windows

The reference servers' READMEs launch npx through cmd /c on Windows. If an npx-based stdio server fails to connect on native Windows (WSL doesn't need this), register it like this:

claude mcp add --transport stdio everything -- cmd /c npx -y @modelcontextprotocol/server-everything

Now test it. Start claude in the same folder, run /mcp to see everything connected with its tools, then ask:

Use the everything server's get-sum tool to add 19 and 23.

Claude Code asks permission for the tool call, then answers 42.

4. Add an HTTP server

claude mcp add --transport http <name> <url>

To try one locally, run the Everything server in HTTP mode in a second terminal, then register its URL:

npx @modelcontextprotocol/server-everything streamableHttp

claude mcp add --transport http everything-http http://localhost:3001/mcp

Hosted servers work the same way, for example claude mcp add --transport http notion https://mcp.notion.com/mcp. If a server uses OAuth, run /mcp inside Claude Code and choose to authenticate, which opens a browser. For a server that takes a static token, add --header "Authorization: Bearer your-token".

5. List, inspect and remove servers

claude mcp list            # every server and its connection status
claude mcp get everything  # details for one server
claude mcp remove everything

Inside a session, /mcp shows status, lists each server's tools and handles OAuth.

6. Share servers with .mcp.json

--scope project writes .mcp.json in the project root, which you commit so the server comes with the repo:

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    },
    "docs-api": {
      "type": "http",
      "url": "${DOCS_API_URL:-http://localhost:3001}/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_API_TOKEN}" }
    }
  }
}

$ followed by a variable name in braces expands from your environment, and :- gives a default, so tokens stay out of the file. In an interactive session, Claude Code asks once before using project servers. claude mcp reset-project-choices clears those answers. claude -p runs load them without asking.

7. Register a stdio server you wrote

Answer projects write servers with the TypeScript SDK, @modelcontextprotocol/server (v2). A minimal one:

mkdir greeter && cd greeter && mkdir src
pnpm init && npm pkg set type=module
pnpm add @modelcontextprotocol/server zod

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";
 
const server = new McpServer({ name: "greeter", 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}!` }],
  }),
);
 
await server.connect(new StdioServerTransport());
console.error("greeter MCP server running on stdio");

Register it with an absolute path, so it starts no matter which folder Claude Code runs in:

claude mcp add --transport stdio greeter -- node "$PWD/src/server.ts"

On Node 22.18 or newer, node runs the .ts file directly. The SDK's own tutorial uses npx tsx src/server.ts, which also works. Start claude, check /mcp, and ask it to greet someone.

For debugging outside Claude Code, the MCP Inspector lets you call tools by hand: npx @modelcontextprotocol/inspector node src/server.ts.

Check it works

claude mcp list

Expected output: one line per server, showing everything (and greeter, if you added it) with its command and a connected status. A failed server says so on its line.

Troubleshooting

Failed to connect in claude mcp list. Run the server command by itself (for example node src/server.ts) and read the error. Common causes: a typo in the path, Node older than the server needs, or a missing pnpm install.

The server connects but shows no tools, or drops after a moment. It's printing to stdout. Change every console.log to console.error.

A slow server times out at startup. Raise the timeout for that run: MCP_TIMEOUT=20000 claude.

A project server never appears. You declined it at the approval prompt. Run claude mcp reset-project-choices and start claude again.

Going further

• Install Claude Code, for passing --mcp-config to claude -p
• Node.js, pnpm and TypeScript