How to connect an MCP server — one command, no JSON editing

Most MCP instructions open with "edit your configuration file and add this JSON." At which point half the readers close the tab.

Good news: that hasn't been necessary for a while. Connecting an MCP server is one command in the terminal, and the editor writes the JSON for you.

Let's do it on a live example. If you're still fuzzy on what MCP even is, start there — this piece is pure practice.

1. Work out which kind of server you have

There are exactly two kinds, and they take different commands.

• Hosted (by URL). Someone already runs it; you got a URL. Nothing to install.
• Local (stdio). A program the agent launches on your machine. You need this when the tool must reach your files, your browser or a database.

Check the server's docs: a URL like https://…/mcp means the first kind. A line like npx -y some-package means the second.

2. Add the server

Run these in a normal terminal, not inside an agent session: you're configuring the tool before the conversation starts.

For a hosted server:

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

Piece by piece:

• claude mcp add — register a server;
• --transport http — it lives at a URL instead of being launched locally;
• claude-code-docs — a name you invent yourself. It labels the server in your list and in the agent's output;
• then the address itself.

For a local server:

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

Two differences. No --transport flag, because local is the default. And crucially: everything after -- is the launch command. That separator is mandatory — without it the arguments scatter.

This example hands the agent a real browser: open pages, click, read. No account needed, just Node.js 18+.

3. Verify the connection — this isn't a formality

The "Added…" message only means the entry was saved. It does not mean the server works. So check:

claude mcp list

What you'll see next to the name:

• ✔ Connected — done, go use it.
• ✘ Failed to connect — no response. For a local server that's normal on the first run while npx downloads the package. Wait half a minute and retry.
• ! Needs authentication — the server is alive but wants a sign-in, either in the browser or via a token.
• ⏸ Pending approval — a server from the project's shared config; approve it once inside a session.

If it needs a token, pass it while adding:

claude mcp add --transport http github https://api.githubcopilot.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

A local server usually wants its key as an environment variable — that's the --env flag:

claude mcp add weather --env API_KEY=your_key -- npx -y weather-mcp

Mind the order: --env comes before the -- separator. Everything after the separator counts as the server's launch command, so the flag would just get swallowed by it.

Which variables a server needs is always in its documentation. On keys themselves — and why they shouldn't sit in your code — we have a separate piece.

4. Try it for real

Start a session and ask for something impossible without the server:

claude

Use the playwright server to open example.com and tell me the page title.

In everyday use you don't name the server — the agent picks its tools itself. Here it's only to prove the answer came through the server rather than out of the model's memory.

Inside a session, /mcp lists your servers with their status and lets you reconnect without leaving the conversation.

5. Decide where the server should live

Scope is fixed when you add a server; changing it means removing and re-adding. Three options:

• local (default) — just you, just this project. Written to ~/.claude.json.
• --scope user — just you, but in every project. Good for general-purpose things like a browser.
• --scope project — a .mcp.json file in the project root. Commit it, and teammates get the server automatically.

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

Forgot where you put one? Ask: claude mcp get <name> shows both the scope and the full address.

What you end up with

Once you see ✔ Connected, the agent has new tools and reaches for them on its own when a task calls for it. You stop copying data from another tab into the chat — the agent goes to the system directly.

And one thing about hygiene, right away. Every connected server permanently occupies part of the context window: its tool names and descriptions load into every session. Five servers kept "just in case" is a visible chunk of context wasted, and money with it.

So the rule is simple: added it, tried it, don't use it — remove it.

claude mcp remove playwright

The server connected but no tools showed up — now what?

Most likely it's missing an environment variable, usually a key. Open /mcp in a session and look at that server's tool list: if it's empty, read the docs and supply what's missing via --env.

Can I just write .mcp.json by hand?

You can, the format is open. But mind two things: the file is read at session start, so restart after editing it, and the path matters (.mcp.json in the project root, not somewhere in a settings folder). The claude mcp add command simply removes both chances to get it wrong.

Does MCP only work in Claude Code?

No. MCP is an open standard and the servers are the same across clients. Only the way you connect differs: a command here, an app setting there. The server itself never needs rewriting.