How to Add an MCP Server to Claude Code

You wired up an MCP server, pasted the command, hit enter — and Claude Code parsed your launch command as its own flags and threw a wall of nonsense. Nine times out of ten it’s one missing --. Here’s how to add MCP servers to Claude Code without tripping over the same rake I did.

What an MCP server actually is

MCP is the Model Context Protocol. An MCP server is just a little process that hands Claude Code new tools and data sources — a Postgres database, your GitHub account, a headless browser, an internal API, whatever. Instead of copy-pasting context into the chat, you plug the source in once and Claude can query it directly, mid-task.

Two flavors matter: local (stdio) servers that Claude launches on your machine as a subprocess, and remote servers it talks to over HTTP or SSE. You add both with the same claude mcp add command — the difference is a flag or two.

Add a local (stdio) server

This is the common case. The syntax:

claude mcp add <name> -- <command> [args...]

That -- is not decoration. It separates Claude’s own flags from the command that launches your server. Everything after -- is handed to the server process untouched. Real example, adding the GitHub MCP server:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

github is the name you’ll see when you list servers. npx -y @modelcontextprotocol/server-github is the actual launch command. Claude runs that as a subprocess and starts talking MCP to it. Skip the -- and Claude tries to interpret npx and its args as flags for itself — that’s the number-one failure and we’ll come back to it in troubleshooting.

Pass secrets with env vars, not plaintext

Most useful servers need an API key or a connection string. Pass them with -e KEY=value, and repeat the flag for as many as you need:

claude mcp add postgres -e DATABASE_URL=postgres://user:pass@localhost:5432/mydb -- npx -y @some/postgres-mcp

The env vars land in the server’s process environment, exactly where the server expects to read them. Do it this way instead of hardcoding a secret into a config file — especially any config you plan to commit. More on that trap below.

Add a remote server

If the server lives on a URL instead of your machine, tell Claude the transport:

# Server-sent events transport
claude mcp add --transport sse linear https://mcp.example.com/sse

# Streamable HTTP transport
claude mcp add --transport http notion https://mcp.example.com/mcp

Remote servers usually want auth. If it’s a static token, pass a header:

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

If the server does OAuth, don’t try to jam a token in on the command line. Add it, then open a Claude Code session and run /mcp — that command lists your connected servers and walks you through authenticating the ones that need a browser login.

Choosing a scope: who gets this server

Every server you add has a scope, set with --scope (or -s). Three options:

• local — the default. Private to you, only in the current project.
• project — shared with your team. Written into a .mcp.json file at the repo root that you commit to git.
• user — available to you across all your projects.

# Just me, this repo
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# The whole team, committed to the repo
claude mcp add --scope project github -- npx -y @modelcontextprotocol/server-github

# Me, everywhere
claude mcp add --scope user --transport sse linear https://mcp.example.com/sse

Project scope is the one that scales. Add a server once, commit the .mcp.json, and every teammate who clones the repo gets the same tooling. It pairs naturally with a good CLAUDE.md file — the config says what tools exist, the CLAUDE.md says how and when to use them.

What the .mcp.json file looks like

Project scope writes a .mcp.json at your repo root. You can also edit it by hand. A local server entry:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "..." }
    }
  }
}

A remote server uses a type and a url instead of a command:

{
  "mcpServers": {
    "myapi": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Use "sse" in place of "http" for the SSE transport. Notice the env block — that’s where the token goes, and it’s why you reference a value rather than pasting the raw secret into a file everyone can read.

Managing servers you’ve already added

Once you’ve got servers configured, these are the commands you’ll actually use day to day:

claude mcp list          # show every configured server
claude mcp get github    # details on one server
claude mcp remove github # rip one out

Two shortcuts worth knowing. If you already have a server defined as JSON, skip the flag juggling and paste it straight in:

claude mcp add-json weather '{"command":"npx","args":["-y","@some/weather-mcp"]}'

And if you’ve already set servers up in Claude Desktop, import them wholesale instead of retyping:

claude mcp add-from-claude-desktop

The security part — read this before you add anything

An MCP server can execute code and read your data. That’s the whole point, and also the whole risk. Treat adding a third-party server exactly like installing a dependency you didn’t write — because that’s what it is.

Claude Code has a guardrail here: project-scoped servers that come from a checked-in .mcp.json prompt you for approval the first time before they’re allowed to run. So when you clone a repo and it ships MCP servers, you get a chance to say no. Use it. Only add servers you trust, and never, ever commit a real secret into .mcp.json — put it in an env var and keep the file clean.

Troubleshooting the three things that actually break

You forgot the --. By far the most common. If Claude Code complains about an unknown flag or mangles your command, check that you have -- sitting right before the launch command. Everything meant for the server goes after it.

Your secret is in a committed file. If you dropped a token straight into .mcp.json and pushed it, that key is now in your git history. Rotate it, move it to an -e KEY=value env var, and re-add the server.

The remote server won’t connect or authenticate. Confirm the transport matches what the server actually speaks — --transport sse vs --transport http. For OAuth servers, don’t fight it on the CLI; open a session, run /mcp, and authenticate through the flow it gives you.

Where this fits

Adding MCP servers is one lever. The bigger picture is running Claude Code so it’s both capable and cheap enough to leave running all day. Two moves compound here.

First, tokens. MCP servers make Claude do more work, which burns more tokens — so the economics matter. I run Claude Code against the z.ai GLM Coding Plan to keep the meter sane; walkthrough is in setting up Claude Code with the GLM API. Full disclosure: https://z.ai/subscribe?ic=BWTG6TRYYQ is a referral link — it helps fund our compute, and it’s not a discount, just the same plan through our link.

Second, instructions. Handing Claude ten tools doesn’t help if it doesn’t know when to reach for each one. That’s a prompting problem, and it’s why I lean on reusable instruction templates — Meta-Prompt Architect is the pack I use to write high-signal, reusable instructions so cheap tokens actually do real work instead of thrashing. Pair it with a tight custom slash command and your MCP-loaded setup starts feeling less like a chatbot and more like a coworker.