How to Add an MCP Server to Claude Code, Step by Step

You have heard that Claude Code can connect to your other tools. It can read your issue tracker, look inside a database, or open a web page in a real browser. The way it does this is called MCP. A search for "claude code MCP server" usually means one thing: you want to add one, and you want clear steps.

This guide gives you those steps. We start with the smallest example that works, then move to harder ones. We also cover what to do when something fails, and how to stay safe. Everything here comes from the official Claude Code documentation, which we read on 9 October 2026. The tool changes often, so if a command behaves differently for you, the official MCP reference is the place to check.

We have not set up every server mentioned here ourselves. We describe what the documentation says, and we say so when we are unsure. If you are new to Claude Code itself, read our guide on using Claude for coding first.

What an MCP server is, in plain words

MCP stands for Model Context Protocol. It is an open standard for connecting AI tools to other systems. The MCP website compares it to a USB-C port: one shape of plug that works with many devices. An AI tool that understands MCP can talk to any server that follows the same rules.

An MCP server is a small program or a hosted service. It gives the AI a few abilities. For example, one server might let Claude search an issue tracker. Another might let it query a database. Another might let it control a browser. Without a server, Claude can only work with the text you paste in and the files in your project. With a server, it can look things up and take actions in the other system.

Think of it like giving a new assistant access to your tools. Before, you had to copy and paste everything for them. Now they can open the tool themselves. That is useful, and it is also the reason you need to be careful, which we cover near the end.

What you need before you start

• Claude Code installed and signed in. If it runs when you type claude, you are ready.
• A terminal open in a project folder. The documentation says any folder works, even an empty one.
• Node.js 18 or newer, only for some servers. Local servers that start with npx need it. Hosted servers do not.

One important detail: run the add command in your normal terminal, not inside a claude chat. You are setting up the server before the conversation starts.

Step 1: Add your first server

The official quickstart uses the Claude Code documentation server. It is hosted online, it needs no sign-in, and it only searches documents. That makes it a safe first test.

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

Here is what each part means:

• claude mcp add tells Claude Code to register a server.
• --transport http says the server lives at a web address. It does not run on your computer.
• claude-code-docs is a name you choose. You could call it docs and it would work the same. Claude Code uses this name to label the server's tools and to refer to it in later commands.
• The web address is where the server is hosted.

When it works, the command prints a message saying it added an HTTP MCP server to "local config". It also shows which file it changed. "Local config" matters. It means the server is saved for you, in this project only. If you open a different project, the server will not be active there. We explain how to change that below.

Step 2: Check that it connected

Run this in your terminal:

claude mcp list

You will see your server with a status. The documentation lists these meanings:

On some older Windows consoles, the check mark and cross do not display. You may see other symbols in their place. The meaning is the same.

Step 3: Use the server in a chat

Start a session:

claude

Then ask Claude to use the server by name:

Use the claude-code-docs server to look up what MCP_TIMEOUT does

You do not usually need to name the server. Claude picks useful tools on its own. We name it here so we know the answer came from the new server and not from some other tool. The first time Claude calls the server, Claude Code may ask for your permission. Say yes if you trust it. In the output, the tool call is labelled with the server name. That label is how you confirm the answer came from the server.

Step 4: Remove it when you are done

claude mcp remove claude-code-docs

This step is optional, but it is a good habit. The documentation says each connected server takes up some space in Claude's context window. The tool names and instructions of every server are loaded into every session. So a server you no longer use is not free. It uses up room that Claude could spend on your real work.

Where servers are saved, and what "scope" means

A server can be saved in three places. The place is called its scope. You pick it with the --scope option.

On Windows, ~/.claude.json means a file called .claude.json in your user folder, for example C:\Users\YourName\.claude.json.

The scope is fixed when you add the server. To change it, remove the server and add it again with a new scope. For example, to use the docs server in every project:

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

To share a server with your team, use --scope project instead. That writes a .mcp.json file. You can commit that file so teammates get the same setup. When they start Claude Code, they will be asked to approve the server first. That prompt exists on purpose. It stops a project you download from starting programs on your computer without asking you.

If you are not sure where a server is saved, run claude mcp get <name>. It shows the scope and the details.

Adding a local server that runs on your computer

Some servers are programs that run on your own machine. They are useful when the tool needs your files, your browser, or a local database. The documentation uses the Playwright server as its example. It gives Claude a browser to open pages and click around, and it needs no account.

claude mcp add playwright -- npx -y @playwright/mcp@latest

This looks different from the first command in three ways:

• There is no --transport option. Local servers use a default type called stdio.
• Everything after the -- is the command that starts the server. This double dash matters. It tells Claude Code that what follows belongs to the server, not to Claude Code. If you forget it, the command may be read wrongly.
• -y tells npx to install the package without asking.

A message saying "Added" means the entry was saved. It does not prove the program runs. So check again with claude mcp list. The first check can show "Failed to connect" while npx is still downloading the package. Wait a moment and run it again. The documentation also notes that Playwright uses the Chrome already on your computer, and you can add --browser firefox to use another browser.

Then try a task, such as: "Use playwright to open https://example.com and tell me the page title." A browser window opens and you can watch it work.

Adding a server that needs you to sign in

Many online services, such as Sentry, Linear and Notion, ask you to sign in before their server works. The method is called OAuth. Here is the documented flow, using Sentry as the example:

1. Add the server as you did before:

   claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

   After this, claude mcp list shows "Needs authentication". That is normal.
2. Start Claude Code and type /mcp. Select the server, press Enter, and choose Authenticate. Your browser opens the service's sign-in page. Approve the connection there.
3. Back in Claude Code, the status changes to connected. Ask something that needs the service, such as "What Sentry projects do I have access to?"

Some servers use a fixed token instead of a browser sign-in. For those, you give the token when you add the server:

claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"

Treat that token like a password. Do not paste it into a chat, and do not commit it to a shared file. If you set the Authorization header yourself and the server rejects it, the documentation says Claude Code reports a failed connection rather than starting the sign-in. In that case, remove the header if you want to use the browser sign-in instead.

Writing the .mcp.json file by hand

The add command writes the file for you. You can also write it yourself. Create a file called .mcp.json in your project folder:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

For a web server, url is the address. For a local server, command and args are the program to run. Claude Code reads this file when a session starts, so close and restart the session after you edit it. The first time it sees a project server, it asks you to approve it.

The documentation also allows you to keep secrets out of the file. You can write ${VAR} in a value, and Claude Code replaces it with an environment variable. You can add a fallback with ${VAR:-default}. If a variable has no value and no fallback, you get a warning.

Other ways to add a server

• From JSON. The command claude mcp add-json <name> '<json>' adds a server from a block of JSON. Be careful with quote marks, because each shell treats them differently.
• From Claude Desktop. The command claude mcp add-from-claude-desktop copies servers from the Claude Desktop app. The documentation says it works on macOS and WSL.
• Other places. The documentation says you can also connect servers from the Claude Code desktop app, from VS Code, and from the web. Connectors you add on Claude.ai load automatically in the command line when you sign in with the same account.

Server names may only use letters, numbers, hyphens and underscores. Other names are skipped.

When something goes wrong

Start by checking the status. Use claude mcp list in your terminal, or /mcp inside a session. Then match your problem to this list, which follows the documentation.

Two more facts from the documentation may save you time. If a hosted server drops during a session, Claude Code tries to reconnect up to five times. Servers that run locally are not reconnected automatically. You can also type /mcp reconnect all to retry every failed server, though the documentation says that needs a recent version.

Hosted or local: how to choose

You now know two kinds of server. A hosted server lives at a web address. A local server is a program that runs on your computer. How do you choose between them? The choice is often made for you, because each service offers one kind. When you do have a choice, think about three things.

• What it needs to reach. If the tool must read your files, drive your browser or reach a database on your own machine, you need a local server. A hosted server cannot see your computer.
• Who runs the code. With a hosted server, the company that owns the service runs the code, and you trust them. With a local server, you download a program and it runs with your permissions on your machine. That is more power, so it deserves more care. Look at who published the package before you run it.
• How much work it is to keep it running. A hosted server needs only a web address. A local one needs Node.js or another runtime, and it can break when a package changes. The documentation notes that local servers are not reconnected automatically, so a crash means you must restart.

For a beginner, our advice is simple. Start with hosted servers from well-known services. Move to local servers only when you have a clear job that needs one.

Questions to ask before you add any server

It is easy to copy a command from a blog post and run it. Slow down for one minute and ask these questions first.

1. Who made it? Is it from the company that owns the service, or from a stranger?
2. What can it do? Can it only read, or can it also write, send or delete?
3. What does it need from me? A token, a key, a sign-in? Would I be comfortable if that key leaked?
4. What will it see? Will it read content from outside, such as emails or web pages? That is where hidden instructions can come in.
5. Do I need it today? If the answer is no, wait. You can always add it later.
6. How do I remove it? You already know: claude mcp remove <name>. Also remember to revoke any token you gave it.

If you cannot answer the first two questions, do not add the server yet.

Why fewer servers is usually better

It is tempting to connect everything. There is a practical reason not to. The documentation says the tool names and instructions of every connected server are loaded into each session, and that this takes room in Claude's context window. The context window is the working memory of the AI for your chat. If much of it is used by tool descriptions, less is left for your actual code and conversation.

The documentation says a feature called tool search is on by default, which helps the tool cope when there are many tools. Still, a small, well-chosen set of servers is easier to understand, easier to secure, and less likely to confuse the AI. A good rule: add one server for one clear job, use it for a week, and then decide if you need another.

Staying safe

This is the part most guides skip, so we give it real space. The official documentation says to connect only servers you trust. Here is the reason. When a server brings in outside content, that content can contain hidden instructions. They try to push the AI into doing something you did not ask for. This is called prompt injection. A web page, a support ticket or an email could carry such text.

You cannot remove this risk completely. You can make it smaller:

• Connect only what you need. Every extra server is extra risk, and it also uses context space.
• Prefer servers from the company that owns the service. For a server from someone else, read what it asks for and who made it.
• Use the least access you can. If a server only needs to read, do not give it a key that can also write or delete. Where possible, use a read-only account.
• Keep live data out while you learn. Do not connect a database with real customer records, or a payment account, while you are experimenting. Use a copy or a test account.
• Keep secrets out of files you share. Use --env or ${VAR}, and never commit tokens.
• Read the permission prompts. When Claude Code asks before using a tool, take a moment to see what it will do.
• Watch what comes out. The documentation says large results are limited. The default output limit is 25,000 tokens, with a warning above 10,000. That is a guard, not a safety check.

If you handle customers' personal data, our guide on what the NDPR means for a small Nigerian website explains why you should be careful with what an AI tool can reach.

A ten-minute practice plan

1. Add the documentation server and check it with claude mcp list.
2. Ask Claude a question that names the server, and look for the server name in the tool call.
3. Run claude mcp get claude-code-docs and find the scope.
4. Re-add it with --scope user, then remove the local copy.
5. Remove it with claude mcp remove and check the list is empty.

After this you will know the whole cycle: add, check, use, move and remove. Every other server follows the same pattern. Only the address, the command or the sign-in step changes.

Mistakes to avoid

• Forgetting the double dash before a local server command.
• Trusting "Added" as proof. Always check the status.
• Adding a server in the wrong scope and then wondering why it is missing in another project.
• Pasting a token into a chat or a shared file.
• Connecting a live database or payment account too early.
• Leaving unused servers connected. They fill the context window.
• Following an old tutorial. The documentation moved to code.claude.com, and old pages may be out of date.

Where to go next

Once the basics feel easy, the official guide shows how to find more servers, how to share them with a team, and how an organisation can control which ones are allowed. If you are not a developer, read is vibe coding bad for non-developers, which explains why a written plan and careful access matter so much. To compare editors that also support MCP, see Kiro vs Cursor: which should a beginner start with, and to see how a written plan works in practice, read spec-driven development with Kiro.