How to Connect an MCP in Claude Code, Step by Step

Connecting an MCP to Claude Code fits in one line: claude mcp add my-server -- npx -y @package/mcp-server. Anyone searching claude code mcp is usually already running Claude Code daily and wants it to talk to something outside the project: a database, a GitHub repo, an internal company system. What’s usually missing isn’t the command, it’s understanding what this protocol is and where it fits next to a skill.

How does Claude Code work?

Claude Code is Anthropic’s command-line interface: install it with one command, launch it by typing claude inside a project folder, and from there it reads files, runs commands, and commits in the same terminal session. By default it only sees what’s in the project. To reach an external system (an API, a database, a third-party service) it needs a connector, and that connector is an MCP server.

What is an MCP server and what is it for?

MCP stands for Model Context Protocol, an open standard created by Anthropic (now governed by the Agentic AI Foundation) for how a model connects to outside tools and data. Before MCP, every integration (Slack, a database, a CRM) needed its own custom code. With MCP, the server exposes its tools in a common format, and any compatible client, Claude Code included, discovers and uses them without anyone hand-building that bridge.

A related search with the same intent is claude skills mcp server: how to build your own MCP server for a skill to call, instead of installing one that’s already published. Its sibling keyword, skills mcp claude code, is the same question in a different order. In both cases the answer is the same: an MCP server is a separate process (it can run locally or remotely) that declares its tools once, and Claude Code connects to it as a client.

How do you connect an MCP server in Claude Code?

The base command is claude mcp add, followed by whatever name you want to give the connection and how to start it:

1
claude mcp add my-server -- npx -y @package/mcp-server

That registers a local server that runs as a process (stdio). If the server lives remotely, the transport to use is HTTP (SSE is deprecated and kept only for compatibility) and the flag changes:

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

Once it’s registered, claude mcp list shows every active server, and inside a session the /mcp command lists the tools each one exposes and its connection status. The first time Claude wants to use one of those tools, it asks for explicit authorization, the same as any other sensitive action.

Some servers need an API key. Pass it with -e:

1
claude mcp add my-server -e API_KEY=xxxx -- npx -y @package/mcp-server

If you already have MCP servers set up in Claude Desktop, claude mcp add-from-claude-desktop imports them without re-typing each one (available on macOS and WSL).

Where do scope and permissions live?

Every connection registers under one of three scopes, and the difference matters more than it looks at first:

• Local (the default): only for you, only in this project. Never shared, never committed.
• Project: saved in an .mcp.json file at the project root, meant to be committed and shared with the team.
• User: global, applies to every project on this machine.

Scope is set with --scope local|project|user. In our experience, the most common mistake is committing an .mcp.json with an API key sitting in plain text: that file gets shared with the whole team, and with anyone who clones the repo, so credentials belong in environment variables, never written directly into the config file.

Skills vs MCP in Claude Code: when to use each one

The underlying question, skills vs mcp, doesn’t have a generic answer. It depends on whether the work is reasoning through steps or connecting to a system that already exists outside Claude Code. A skill is a folder of instructions, scripts, and templates that fixes how Claude solves a task it repeats: the logic lives inside the project, and you’re the one who wrote it. An MCP server is the opposite, a bridge to something that already exists and that you’re not going to rewrite: the production database, the company’s Jira, the CRM. They don’t compete. A well-built skill calls an MCP when the step it needs is “talk to this external system,” instead of trying to reimplement that connection from scratch.

The useful question isn’t which one to use in general, it’s where the data or the action comes from: if it lives inside the project and the task repeats the same way each time, that’s a skill. If it lives outside and already has an API, that’s an MCP.

What goes wrong when connecting an MCP?

Most failures fall into three buckets. If claude mcp list doesn’t show a server you just added, it’s almost always a syntax error in the startup command, not the protocol itself. Test that same command outside Claude Code first. If the server shows up but its tools don’t appear in /mcp, the server failed to start (check its logs) or it needs authentication that hasn’t completed yet. And if a remote server uses OAuth, the token can expire; open /mcp and pick Re-authenticate on that server, or run claude mcp login <name> to sign in again.

With those three points covered, connecting an MCP in Claude Code is a command and a scope decision, not an integration you have to build from scratch.