Claude Code MCP: how to connect Claude Code to MCP servers

Claude Code ships with first-class support for the Model Context Protocol (MCP). By the end of this guide, you'll have Claude Code connected to at least one MCP server, calling tools against a real system, and configured for a team — not just your laptop.

Prerequisites: Claude Code installed and authenticated (see Claude Code's docs for install), Node.js 22+ (only if installing via npm; the native installer needs no Node.js runtime), and shell access. Time required: about 20 minutes for a single server, longer if you're wiring OAuth.

A quick vocabulary check before we start. Claude Code is Anthropic's terminal-based coding agent. MCP is the open protocol Claude uses to discover and invoke tools exposed by external servers. An MCP server is any process — local binary, remote HTTP endpoint, container — that speaks MCP and exposes tools. If you want a deeper protocol explainer, see our deep-dive on what an MCP server is.

Step 1 — Confirm your Claude Code version supports MCP

MCP support has shipped in Claude Code from early releases, but the CLI surface has changed. Confirm you're on a current build before doing anything else — the claude mcp subcommand and config file layout have moved between versions.

Run:

claude --version
claude mcp --help



You should see subcommands including add, list, remove, and get (recent versions also include add-json, login, and logout). If claude mcp isn't recognised, upgrade before continuing.

Step 2 — Pick your first MCP server

Start with one server that gives you something concrete to test. Two categories of first choice:

• A reference server from the MCP org — filesystem, git, or fetch. These run locally over stdio, no auth, no network. Good for a five-minute smoke test.
• A vendor-provided remote server — GitHub, Linear, Sentry, or similar. These run over HTTP with OAuth. Slower to set up but closer to what you'll actually use day to day.

For this guide we'll wire up two: the filesystem reference server (local, stdio) and a remote server over HTTP with OAuth. If you cover both transports once, every other server is a variation.

Step 3 — Add a local stdio server

Stdio servers run as child processes of Claude Code. You give the CLI a command to launch and it manages the process lifecycle.

Add the filesystem server, scoped to a specific directory:

claude mcp add filesystem \
 -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects



The -- separates Claude's flags from the command Claude will run. Everything after -- is executed verbatim as the server process.

Verify it registered:

claude mcp list



You should see filesystem listed with its command. Now open Claude Code and ask it to list files in the project directory. If the tool call succeeds, the server is working. If Claude says it can't find a filesystem tool, restart the Claude Code session — MCP servers are loaded at session start.

Step 4 — Add a remote HTTP server with OAuth

Remote servers run somewhere else and Claude Code connects over HTTP. Most production MCP servers you'll care about — the ones exposing real SaaS products — fall into this category, and most require OAuth so tool calls run as the authenticated user rather than a shared service account.

Add a remote server (using GitHub's hosted MCP server as the example):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/



On first use, Claude Code will detect the server requires OAuth and open a browser window for you to authorise. Complete the flow and the tokens are stored locally. Tool calls from this point run as your GitHub user, with your permissions.

This is the pattern you want in production. Shared service accounts collapse the audit trail and blow past least privilege — every tool call looks like it came from the same actor. Delegated auth at the tool call is what actually holds up under security review (we go deeper on this in agent identity vs user identity).

Step 5 — Choose the right scope for the config

Claude Code supports three config scopes. Picking the wrong one is the most common setup mistake.
‍

For a team, the servers everyone needs go in project scope. That puts an .mcp.json file in the repo root, which Claude Code reads on session start. Everyone on the team gets the same server list without doing setup.

Re-add a server at project scope:

claude mcp add -s project linear \
 --transport http https://mcp.linear.app/mcp



Commit .mcp.json. Teammates run claude in the repo and the server is already there — they only have to complete OAuth once.

Step 6 — Design what the agent actually sees

Here's where a lot of setups quietly fail. MCP servers often expose dozens of tools. Claude has to pick the right one from that list on every turn, and tool selection accuracy drops as the catalogue grows.

Two things to do before you declare the setup finished:

1. List what each server exposes. Inside Claude Code, ask "what tools do you have available?" and read the list. If a server exposes 40 tools and you only need 6, that's 34 tools of noise on every prompt.
2. Turn off servers you don't need for the current task. Claude Code lets you toggle MCP servers per session from the @ menu (v2.0.10+); there's no CLI enable/disable yet, so use the in-session UI or edit disabledMcpjsonServers in settings.json to keep servers dormant.

If you're building an MCP server yourself for a product your team owns, the same discipline applies at the source: expose the workflows agents actually need, not a 1:1 mirror of your REST API. We cover this in OpenAPI endpoint curation for MCP and, more broadly, in how many tools an AI agent should have.

Step 7 — Debug with MCP Inspector when things break

When a tool call fails or Claude picks the wrong tool, don't debug inside Claude Code — the loop is too slow and the traces are too abstract. Use MCP Inspector, the official debugging tool from the MCP project.

npx @modelcontextprotocol/inspector \
 npx -y @modelcontextprotocol/server-filesystem /tmp



Inspector gives you a UI to list tools, invoke them by hand, and see the raw JSON-RPC exchange. You can catch schema mismatches, auth failures, and malformed responses in seconds. Full walkthrough in our MCP Inspector guide.

Common pitfalls

Server doesn't appear after claude mcp add. Claude Code loads MCP servers at session start. Quit the session and reopen it.

OAuth loop that never completes. The redirect URL registered with your OAuth provider has to match what Claude Code sends. For vendor-provided remote servers this is handled for you. For servers you host yourself, check that the redirect URI in your OAuth app matches Claude Code's callback exactly.

Tool calls work, but Claude picks the wrong tool. Almost always a description problem, not a model problem. Read what the server actually exposes to Claude — vague descriptions like "query the database" collide when several servers offer similar tools. Our guide on writing tool descriptions for LLM agents covers the fixes.

Project scope config not picked up. Claude Code prompts once to approve project-scoped servers as a safety check — it won't auto-load servers a teammate committed without your consent. Approve the prompt and it will load on future sessions.

Every tool call runs as the same user. You're using a shared token, not delegated auth. Fine for a solo project, dangerous for anything multi-user. Switch to a server that supports OAuth and let each user authenticate themselves.

That's the full setup: local server, remote server with OAuth, right scope for your team, curated tool surface, and a debugging loop that isn't Claude Code itself. From here, adding more servers is a repeat of Step 3 or Step 4.