How to Connect MCP Servers to Claude Code: Your First claude mcp add

"I get what MCP is, but how do I actually connect one from the terminal?"

Short version: it's one line. Type claude mcp add --transport http name address in your terminal, and an MCP server gets registered. Check that it connected with claude mcp list; remove it with claude mcp remove name. What used to be picking a connector on the web, this one command handles from the terminal instead. If last lesson had you ask Claude Code your first question and get an answer, today's the day you wire an outside service into that same session. Just here to check the claude mcp add syntax? This lesson alone covers that.

claude mcp add

The command that registers one MCP (Model Context Protocol) server with Claude Code. Once registered, the server's address gets written to a config file, and Claude Code adds that server's tools to its own tool list. What's a screen for turning on a connector on the web becomes this one line in the terminal.

How is a web connector different from a CLI connection?

The underlying spec is the same. The connector you used to link Drive to Claude in the AI Connect track runs on MCP too. The official docs state that connectors in Anthropic's directory use the same MCP infrastructure as Claude Code. Only where you plug it in changes.

Here's a nice bit of news. You don't have to reconnect anything you've already set up on the web. If you're logged in with a claude.ai subscription account, connectors you added on the web come along automatically. Type /mcp inside a session and you'll see them in the list, tagged as coming from claude.ai.

You already have commands. Why do you need MCP too?

Here's a point that trips people up. Claude Code already has hands, even before you connect any MCP server. Read for opening files, Edit for changing them, Grep for searching content, Bash for running commands: these built-in tools are there from the start. When last lesson's "what's in this folder?" got an answer, that was these built-in tools at work. So why would you ever need MCP?

The split comes down to one thing. If the job ends on your own computer, the built-in tools are enough. That covers searching folders and editing files. If you need data or functionality that an outside service holds, that's when MCP comes in. Things like a Notion doc or a ticket in your issue tracker, nothing that lives on your hard disk. It's the difference between grabbing something off your own shelf and having to call the person in charge next door.

There's overlap too. GitHub is the clearest case. You can install the gh command-line tool and call it through Bash, or connect the GitHub MCP server the official docs cover. When both are available, Claude picks whichever fits the situation on its own. Want a specific server to handle it? Just name that server in your question. You can tell which path it took from the response, since MCP tools carry a mcp__servername__toolname tag.

Still not sure which is which? Use these four criteria.

That last row is a cost the official docs spell out directly. It's why "just connect everything" isn't the right instinct.

Hands-on: connecting one server with claude mcp add

All you need is Claude Code, installed and logged in. If you haven't done that yet, go through the Claude Code install lesson first.

Today's server is the Claude Code docs MCP server, the same one the official docs use as their first example. Three reasons it's a good pick: no signup or API key required, it's a remote server so nothing installs on your own computer, and all it does is search documentation, so there's no risk of breaking anything.

Step 1: Register the server

Type this in your terminal, not inside a claude session. It's a setup step you do before the conversation starts.

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

Let's break it down piece by piece.

• claude mcp add, the command that registers a server.
• --transport http marks this as a remote server you reach by address, not a program running on your own computer. Short form: -t http, same thing.
• claude-code-docs, a name you make up yourself. docs would work exactly the same. It shows up as the tool tag in responses, and you'll use this same name to remove it later.
• The last part is the address where the server is listening.

On success, you'll see a line reading Added HTTP MCP server claude-code-docs with URL: ... to local config, along with a File modified: line pointing to the config file that just changed.

Step 2: Check that it connected

Seeing Added doesn't mean it's actually connected. This command only saves the configuration; it doesn't check whether the address or credentials are correct.

claude mcp list

The status shows up right next to the name. If today's server reads something like claude-code-docs: ... (HTTP) - ✔ Connected, you're set.

On an older console like Windows 10's default one, you'll see √ instead of ✔ and × instead of ✘. Same meaning.

Step 3: Ask a question through the connected tool

Now open a session and try it out.

claude

Type this into the input box.

Using the claude-code-docs server, find out what MCP_TIMEOUT does

If a permission prompt shows up, approve it. Normally you don't need to name the server at all, since Claude picks the right tool on its own. The reason to name it here is to keep the answer from drifting off to a different tool, like a web search. If the tool call carries a claude-code-docs tag, that's your proof the answer came from the MCP server.

Step 4: Checking and removing

You'll use checking and removing about as often as registering.

claude mcp list                    # every registered server and its status
claude mcp get claude-code-docs    # details for one server, including its saved scope
claude mcp remove claude-code-docs # unregister it

Inside a session, type /mcp. You'll see the list, and you can pick a server to reconnect or authenticate. If you just want to turn it off for a while, toggling it off from this screen stops the connection without losing the configuration. Once you're done with this exercise, I'd recommend removing it. Even a server you're not using takes up space every session.

Where does a registered server get stored?

Without any options, claude mcp add saves to local scope: visible only to you, and active only in the folder where you registered it. The official docs call this a scope, and there are three of them.

If you're working solo, local and user are the only two you need to know. Add --scope user to keep the connection with you no matter which folder you move to.

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

The scope is locked in the moment you register. Changing it means removing the server and registering it again. On Windows, ~/.claude.json usually maps to C:\Users\your-username\.claude.json. You'll probably never edit it by hand, but knowing where it lives gives you somewhere to look if a server goes missing.

Common problems

• /mcp shows "No MCP servers configured." You probably registered it from a different folder. Local scope is tied to the folder you registered it in. Register it again from your current folder, or use --scope user instead.
• It's registered, but you're seeing ✘ Failed to connect. Suspect the address first. claude mcp list shows the error the server returned right after the status. If you typed a path that doesn't exist and got a 404 back, selecting that server inside /mcp shows a MCP endpoint not found at ... message. Check the address with claude mcp get name, then remove and re-register it.
• You're seeing "Connection timed out." The default startup wait is 30 seconds. Try extending it in milliseconds, like MCP_TIMEOUT=60000 claude. On PowerShell, write it as $env:MCP_TIMEOUT = "60000"; claude.
• A server run through npx won't come up. A server launched via npx needs Node.js 18 or later. The first run can look like a brief failure just from downloading the package, so wait a moment and run claude mcp list again.
• It's connected, but there isn't a single tool. This happens when an environment variable the server needs, usually an API key, is missing. Register it again with --env KEY=value added.
• Registration itself is blocked on a work account. An admin has restricted which servers can be used. You'll see a message that spells out the policy directly, something like Cannot add MCP server "name": not allowed by enterprise policy. This isn't something you did wrong, so reach out to whoever manages that policy.

One safety rule worth calling out. Don't connect just any server. The official docs state plainly that while Anthropic reviews connectors against directory-listing criteria, it doesn't security-audit individual MCP servers. The more a server pulls in outside content, the more risk there is of a hidden instruction slipping in through that content. Only connect to servers officially run by companies you trust.

I ran into the terminal side of this first. Back then I had no confidence I was doing it right. I didn't know whether a connection, once made, stayed made, or whether I had to redo it every time, and I had no way to check whether it had actually worked, so I'd just try something and assume it had worked if nothing broke.

That's why I put step 3 into this lesson. One habit, running claude mcp list right after connecting, gets rid of that uncertainty completely. I didn't even know that command existed for a long time, so I went without checking for far too long.

The first time a server that needed authentication popped a browser window open on its own, that surprised me too. It felt strange that one line typed into a terminal could open a browser. Looking back now, that's exactly where the approval step belongs, since a human needs to actually see it and click it.

Track complete: six steps out of the browser

Let's look back at the steps this track walked through. Check whether all six of the following are done. If any of them are missing, go back to that lesson.

• 1. The Claude lineup, picked the one product that fits your work.
• 2. Desktop app and local folders, connected a folder on your own computer inside the app.
• 3. First steps in the terminal, opened a terminal and typed three basic commands.
• 4. Installing Claude Code, saw claude launch already logged in.
• 5. First run, asked a first question and got an answer.
• 6. Today, registered a server with claude mcp add and confirmed ✔ Connected.

If you've made it this far, you're done stepping outside the browser. The terminal probably felt unfamiliar when you started this track; now you're asking AI questions from that same screen and wiring in outside services besides. The story of editing files directly and running commands continues in the Claude Code track.