How to Add an MCP Server to Claude Code (Tutorial)

To add an MCP server to Claude Code you run one command: claude mcp add, followed by a name and either the server's URL (for a remote server) or the command that starts it (for a local one). You then check the connection with claude mcp list, or with /mcp inside a session, and Claude can use that server's tools. This tutorial connects one remote and one local server, explains the three scopes, and ends with the security rules we follow on client projects.

Every command comes from the official Claude Code documentation, and we ran them on November 4, 2026 with Claude Code 2.1.318 on macOS. If you want AI to work with your company's own systems, this is the same mechanism we use in our AI development projects.

What an MCP server is

MCP (Model Context Protocol) is an open protocol that standardizes how an AI application connects to outside data and tools. An MCP server is a program that exposes those tools: reading files, querying a database, opening a ticket, searching documentation. Claude Code is the client: it connects to the server, sees which tools it offers, and calls them when a task needs them, with your permission.

The latest version of the specification is 2026-07-28, which makes the protocol stateless (there is no protocol-level session anymore). You don't need any of that to connect a server: the command is the same.

There are two ways to connect:

• HTTP: the server runs on the internet and you connect by URL. The documentation recommends it when it's available. The SSE transport is deprecated.
• stdio: the server is a program Claude Code starts on your machine and talks to over standard input and output.

Requirements

• Claude Code installed. The setup page lists macOS 13 or later, Windows 10 1809 or later, Ubuntu 20.04 or later, Debian 10 or later, or Alpine 3.19 or later.
• An account with Claude Code access: Pro, Max, Ultra, Team, Enterprise or Console. The free claude.ai plan doesn't include it.
• For local servers distributed through npm, Node.js; for Python ones, uvx. Each server's README states the version it needs.

Check your version first:

claude --version

How to add an MCP server to Claude Code, step by step

1. Add a remote server (HTTP)

   The Claude Code documentation runs its own MCP server, with no authentication, meant as a first server to try. From your project folder:

   claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

   The general form is claude mcp add --transport http <name> <url>. If the server needs an authorization header, add --header "Authorization: Bearer <token>"; if it uses OAuth, you sign in afterwards from /mcp.

2. Add a local server (stdio)

   For a server that runs on your machine, everything after -- is the command that starts it. This example uses the Filesystem reference server, which can only read and write inside the folder you give it:

   claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ./docs

   If the server needs environment variables (an API key, for example), pass --env KEY=value before the name. The Filesystem server README asks for Node.js 24 or later when you run it with npx; in our test it also worked on Node.js 22, but follow the official number. On Windows, the same README recommends launching npx through cmd /c.

3. Check the connection

   claude mcp list
   claude mcp get claude-code-docs

   claude mcp list checks every server and shows its status: ✔ Connected when it responds, ✘ Failed to connect when it didn't start, and ! Needs authentication when you still have to sign in. A server downloaded with npx can fail the first time while it installs; try again.

   Inside a Claude Code session, /mcp shows the same servers, lets you sign in to OAuth servers, and lets you disable one without removing it.

4. Use it in a task

   Start Claude Code and ask for something that needs the server, for example: "Search the Claude Code docs for how to share MCP servers with my team." The first time Claude wants to call one of the server's tools, it asks for your permission.

5. Remove it when you no longer need it

   claude mcp remove claude-code-docs

   Every connected server loads its tool names and instructions at the start of all your sessions; full tool definitions load only when needed. Still, connect only the ones you use.

Scopes: local, project or user

The --scope option decides where the configuration is stored and who sees it:

To share a server with your team, use the project scope and commit .mcp.json:

claude mcp add --transport http claude-code-docs --scope project https://code.claude.com/docs/mcp

For security, Claude Code asks for approval in interactive sessions before it uses a server that comes from a .mcp.json file. Until you approve it, claude mcp get shows it as pending approval. To decide again, claude mcp reset-project-choices clears those choices.

Don't put secrets in .mcp.json: the documentation supports environment variables with ${VARIABLE} or ${VARIABLE:-default} in the command, arguments, URL and headers.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Common mistakes

• The name goes after --env. If you write claude mcp add --env KEY=value my-server -- …, the CLI can read the name as another --env value. Put another option between them, such as --transport stdio.
• The server is slow to start. Raise the timeout with the MCP_TIMEOUT variable (in milliseconds), for example MCP_TIMEOUT=10000 claude.
• Responses are too long. Claude Code warns when an MCP tool returns more than 10,000 tokens and caps output at 25,000 by default; change it with MAX_MCP_OUTPUT_TOKENS.
• A team server doesn't show up. Check that you approved it: servers from .mcp.json don't connect until you do.

Security: what access you are granting

An MCP server acts with whatever access you give it. The Claude Code security documentation recommends writing your own servers or using ones from providers you trust, and states that Anthropic does not audit the security of MCP servers. The MCP guide adds that servers which fetch outside content expose you to prompt injection.

The rules we follow:

• Connect only servers from providers you know, or code you have reviewed.
• Grant the least access possible: one specific folder, a read-only database user, a narrowly scoped token.
• Keep secrets out of .mcp.json; use environment variables.
• Review tool permissions in Claude Code before approving actions that write or delete.
• For internal systems (ERP, billing, CRM), your own MCP server gives you control over which data and actions it exposes, with a log of every call.

FAQ

What is the command to add an MCP server to Claude Code? claude mcp add. For a remote server: claude mcp add --transport http <name> <url>. For a local one: claude mcp add <name> -- <command> [args].

Where does Claude Code store MCP configuration? In ~/.claude.json for the local and user scopes, and in .mcp.json at the project root for the project scope.

Does it work the same on Windows? Yes. The documentation says claude mcp add works the same in PowerShell and Command Prompt. Some local servers ask you to launch npx through cmd /c; check their README.

Can I connect Claude Code to my company's systems? Yes, with an MCP server that exposes only what you need from those systems. That's an API integration project: we define which data and actions are published, with which permissions, and how they are audited.