Claude Code MCP: How to Add and Test an MCP Server

Out of the box, Claude Code can read your files, run commands, and edit code. But it can’t see your GitHub issues, query your production database, or click around a live web page. Claude Code MCP closes that gap: the Model Context Protocol (MCP) is an open standard that lets Claude Code plug into external tools and data sources through small programs called MCP servers.

This guide walks you through the whole loop in plain English. You’ll learn what you need before you start, how to add an MCP server with a single command, and — the part most tutorials skip — how to confirm the connection actually works before you rely on it. No prior MCP experience required.

What you need before you start

Before adding any MCP server, you need a working Claude Code installation, a terminal you’re comfortable opening, and the runtime the server expects — usually Node.js for npx-based servers or Python for ones launched with uvx.

Most beginners trip over the runtime, not Claude Code itself. A huge share of MCP servers are distributed as Node packages and start with a command like npx -y some-mcp-server. If Node.js isn’t installed, that command fails and Claude Code reports the server as “failed” with no obvious reason why. Other servers ship as Python packages and launch through uvx, so you’ll want Python and uv available too.

Here’s a quick checklist before you continue:

Claude Code is installed and runs. If you haven’t set it up yet, start with our install Claude Code walkthrough.
You know how to open a terminal in your project folder. If the command line feels intimidating, Claude Code for non-coders eases you in.
The right runtime is present for the server you want — Node.js for npx servers, Python plus uv for uvx ones.
You have any credentials the server needs — an API token, a connection string, or an OAuth login. Keep these handy; you’ll pass them in when you add the server.

If you’re still fuzzy on what an MCP server actually is, the short answer is “a small adapter that exposes one external system to an AI tool.” Our explainer on what is an MCP server goes deeper, and MCP vs function calling covers why the protocol exists at all.

How to add an MCP server in Claude Code

You add an MCP server with the claude mcp add command, telling it the server’s name, how it’s launched (the transport), and any credentials it needs — Claude Code stores the configuration so the server is available the next time you start a session.

There are two common transport types, and which one you use depends on how the server runs:

stdio — the server runs locally as a subprocess on your machine. Claude Code talks to it over standard input/output. Most file-system, database, and developer tools use this.
HTTP — the server is a hosted service you reach over the network. You point Claude Code at a URL.

Adding a local (stdio) server

For a local server, put the launch command after a -- separator so Claude Code knows everything that follows belongs to the server, not to claude itself:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

That registers a server named filesystem that Claude Code starts by running the npx command. The ~/projects at the end is an argument passed straight to the server — here, the directory it’s allowed to read.

If the server needs a secret, pass it with -e for an environment variable:

claude mcp add github -e GITHUB_TOKEN=your_token_here -- npx -y @modelcontextprotocol/server-github

Adding a remote (HTTP) server

For a hosted server, set the transport to http and give it the URL:

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

If a remote server expects an auth header instead of an env var, use -H:

claude mcp add --transport http myservice --header "Authorization: Bearer your_token" https://api.example.com/mcp

Choosing a scope

By default, a server you add is local — available only to you, only in the current project. You can widen that with --scope:

--scope local (the default) — just you, just this project.
--scope project — shared with everyone on the project via a committed .mcp.json file. Great for teams; clone the repo and the server is already configured (each teammate gets a one-time approval prompt the first time).
--scope user — available to you across every project on your machine.

Pick project scope when the whole team should use the same tool, and user scope for personal utilities you want everywhere. Because exact flags and server packages change over time, always cross-check against the official Claude Code docs before pasting a command from anywhere — including this article.

One word of caution: an MCP server runs real code with whatever access you grant it. Only add servers you trust, and read MCP security before connecting anything that touches sensitive data or production systems.

How to test that the server works

To test an MCP server, start a Claude Code session and run the /mcp command — it lists every configured server with its connection status, so a “connected” line confirms the setup worked before you ask Claude to use the tool.

Don’t assume a successful claude mcp add means the server is live. The add command only writes configuration; the actual connection happens when a session starts. Testing is a two-layer check: first confirm the connection, then confirm the tools work.

Layer 1 — confirm the connection

Open Claude Code in your project and type:

/mcp

You’ll see each server listed with a status. A connected server is ready to go. If you see “failed” or “connecting” that never resolves, the usual culprits are:

Missing runtime — Node.js or Python isn’t installed, so the launch command can’t run.
Wrong credentials — a bad token or missing env var; the server starts but rejects the connection.
A typo in the command or URL — re-run claude mcp list to see exactly what was saved.

Layer 2 — confirm the tools

Once the server shows as connected, give Claude a task that forces it to use the new tool. If you added a GitHub server, ask it to list your open issues. If you added a filesystem server scoped to a folder, ask it to summarize what’s in that folder.

The first time Claude calls a server, it pauses and asks for permission to use the new tool. Approve it, and the request goes through. If Claude returns real data from your external system, the integration works end to end. If it answers from general knowledge instead of calling the tool, nudge it: “Use the GitHub MCP server to do this.”

Managing servers later

A few housekeeping commands round things out:

claude mcp list — show every configured server.
claude mcp get <name> — see the details of one server.
claude mcp remove <name> — delete a server you no longer need.

Once you’re comfortable with one server, adding more is the same loop every time. From there you can layer on Claude Code subagents and Claude Code hooks to automate bigger workflows, and browse the best MCP servers to find tools worth connecting next.

FAQ

What is MCP in Claude Code?

MCP stands for Model Context Protocol, an open standard that lets Claude Code connect to external tools and data sources. Instead of being limited to reading files and running commands, Claude Code can use MCP servers to query databases, manage GitHub issues, control browsers, and more. Each capability comes from a separate MCP server you add to your configuration.

How do I add an MCP server to Claude Code?

Use the claude mcp add command in your terminal, followed by a name for the server and how it’s launched. For a local server you put the launch command after a -- separator; for a remote one you set --transport http and give a URL. Claude Code saves the configuration so the server is available in future sessions.

How do I know if my MCP server is connected?

Start a Claude Code session and run the /mcp command. It lists every configured server with its current status, so a “connected” entry confirms the setup worked. If a server shows as failed, check that the required runtime is installed and that any credentials are correct.

What’s the difference between stdio and HTTP MCP servers?

A stdio server runs locally as a subprocess on your machine and communicates over standard input/output — typical for file-system and developer tools. An HTTP server is a hosted service you reach over the network by URL. You choose the transport with the --transport flag when adding the server, and remote servers often need an auth header instead of a local environment variable.

Are MCP servers safe to use?

MCP servers run real code with the access you grant them, so safety depends on trusting the source. Only add servers from reputable publishers, give them the narrowest scope and permissions they need, and be especially careful with anything touching production systems or sensitive data. Reviewing MCP security basics before connecting is well worth the few minutes.

Conclusion

Connecting an MCP server to Claude Code is a short, repeatable loop: make sure your runtime and credentials are ready, run a single claude mcp add command with the right transport and scope, then verify with /mcp before you depend on it. The “test it first” habit is what separates a setup that quietly fails from one you can trust.

Once the pattern clicks, the rest of the MCP ecosystem opens up. If you’re newer to the tool overall, the Claude Code tutorial covers the fundamentals, and the Claude Code guide ties everything together. From there, deciding which tools to reach for — servers, subagents, or skills — is its own skill; our breakdown of Claude skills vs MCP vs subagents helps you pick the right one for the job.