How to add an MCP server to Claude Code

MCP (Model Context Protocol) servers let Claude Code use external tools: databases, repositories, your own infrastructure, or any API you want to expose to it. Adding one takes a single command, but there are a few ways to do it depending on the kind of server. Here are the ones I use the most.

What an MCP server is

An MCP server is a program that exposes tools, resources and prompts through a common protocol. Claude Code connects to it and can call those tools while working on a task. There are two kinds of servers, depending on how they communicate:

• Remote (HTTP): they live at a URL and are reached over the network. This is the recommended option today.
• Local (stdio): Claude Code launches a process on your machine and talks to it through standard input and output.

Adding a remote server over HTTP

This is the simplest case. You only need a name of your choice and the URL:

claude mcp add --transport http my-server https://example.com/mcp

If the server uses a token or an API key instead of OAuth, you can send a header with every request:

claude mcp add --transport http my-server https://example.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

If authentication is done through OAuth, add the server without a header and, from inside Claude Code, run /mcp to sign in.

Adding a local server over stdio

For servers that run on your machine, everything after -- is the command that starts the server:

claude mcp add my-server -- npx -y server-package

If it needs environment variables, such as an API key, pass them with --env:

claude mcp add my-server --env API_KEY=your_key -- npx -y server-package

Choosing the scope

You can decide where the configuration is stored with --scope:

• local: only for you and only in the current project. This is the default.
• project: stored in a .mcp.json file at the project root, meant to be shared with your team through the repository.
• user: available to you across all your projects.

claude mcp add --transport http --scope project my-server https://example.com/mcp

If you are sharing the server with your team, use project and don’t put tokens inside the file. It’s better for everyone to use their own.

Checking and managing your servers

These commands show what you have configured:

claude mcp list
claude mcp get my-server
claude mcp remove my-server

Inside a Claude Code session, /mcp shows the status of each server and lets you sign in to the ones that need it.

If something fails

• Check that the URL is reachable from your machine and ends in the correct path for the server.
• If you use stdio, run the server command by hand to see whether it prints any error.
• Make sure the token in the header is correct and has no extra spaces.
• Restart the Claude Code session after changing the configuration.

With this you can connect your own MCP servers to Claude Code and give it access to the tools you need.