You find an MCP server that would save you hours, then the setup instructions send you hunting for the right config file to hand-edit JSON and guess which scope it belongs in. One typo and the server doesn’t load, and you’re left guessing why.
You don’t need to touch that file. MCP (Model Context Protocol) servers give Claude Code access to outside tools and data — a Notion workspace, a Playwright browser, a private API — and Claude Code’s built-in claude mcp command adds, checks, and removes them for you. This guide walks through both connection types and how to confirm one actually works, in about 2 minutes.
Quick Start
Connect a remote HTTP-based MCP server in one line — no local install, no package to run.
claude mcp add --transport http notion https://mcp.notion.com/mcp
Restart Claude Code, then run /mcp inside a session to see it listed as connected. Total time: about 2 minutes.
⚡ Copy This Prompt: Let Claude Code Install and Verify It For You
Skip Steps 1-5 below entirely and hand the whole thing to the agent instead. Fill in the bracketed line with the server you want, paste the rest as-is:
You have access to the `claude mcp` CLI in this project. Do the following and report back — do not tell me it's done unless step 3 actually confirms it:
1. Run `claude mcp list` to see what's already configured.
2. Add this MCP server: [PASTE THE SERVER'S NAME, URL/PACKAGE, AND TRANSPORT TYPE HERE — e.g. "notion, https://mcp.notion.com/mcp, http" or "airtable, npx -y airtable-mcp-server, stdio with AIRTABLE_API_KEY=..."]
3. Run `claude mcp list` again and confirm the server shows as Connected.
4. If it does NOT show Connected, do not report success. Tell me: the exact status shown, the most likely cause (missing auth, wrong URL/package name, missing prerequisite), and the specific command to fix it.
This works because Claude Code can run its own CLI commands in a session — it adds the server, re-checks the connection, and only tells you it’s done once claude mcp list actually agrees.
What You’ll Need
| Requirement | Why You Need It | Time |
|---|---|---|
| Claude Code installed | The claude mcp command ships with it — nothing extra to install |
0 min |
| An MCP server URL or package name | What you’re actually connecting to (remote HTTP endpoint or local npm package) | ~1 min to find |
| Node.js (for local servers only) | Most stdio MCP servers run via npx
|
~5 min if missing |
| API key or token (some servers) | Private servers need auth headers or env vars to connect | ~2 min |
Step-by-Step Setup
Prefer to do it by hand instead of delegating to the agent? Here’s the manual version of the same steps.
Step 1 — Pick a connection type
~1 min
Remote HTTP is the recommended default — the server runs elsewhere and Claude Code just connects over the network. Local stdio runs the server as a process on your own machine, usually via npx. Use HTTP whenever the tool offers it; fall back to stdio for local-only tools like a filesystem or browser server.
Step 2 — Add a remote HTTP server
~1 min
Basic syntax, plus a real example connecting to Notion:
claude mcp add --transport http notion https://mcp.notion.com/mcp
If the server needs a bearer token, pass it with --header:
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
Step 3 — Or add a local stdio server
~2 min
Use -- to separate Claude’s own options from the command that launches the server. Example: adding the Airtable server with an API key passed as an environment variable:
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server
Step 4 — Choose a scope
~1 min
User scope makes the server available across every project on your machine. Project scope writes the server definition into a .mcp.json file in the project root, so it can be committed and shared with teammates:
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp
A project-scoped server can also be defined directly in .mcp.json:
{
"mcpServers": {
"claude-code-docs": { "type": "http", "url": "https://code.claude.com/docs/mcp" },
"playwright": { "type": "stdio", "command": "npx", "args": ["-y", "@playwright/mcp@latest"] }
}
}
Step 5 — Approve and start using it
~1 min
Run claude to start an interactive session. On first launch, project-scoped servers from .mcp.json show a one-time approval prompt — accept it, and the server’s tools become available in that session.
One command plugs a new server into Claude Code, and /mcp shows what’s connected.
What Each Piece Does
| Piece | What It Does |
|---|---|
| Transport (http / stdio) | How Claude Code talks to the server — over the network, or as a local process |
| Scope (user / project / local) | Who can see the server — just you everywhere, or a shared project team |
.mcp.json |
The project-level config file that lists shared servers, meant to be committed |
--header / --env
|
Passes auth tokens or API keys to the server without hardcoding them in the command |
/mcp panel |
In-session view of every connected server and its live status |
Verify the Connection
List every configured server and its health at a glance:
claude mcp list
Here’s what the status column actually looks like, and what each one means:
✔ notion Connected
! secure-api Needs authentication
✘ airtable Failed to connect
⏸ claude-code-docs Pending approval (run claude to approve)
✔ Connected is the only state that means “working.” Everything else needs action: ! Needs authentication (add the missing token), ✘ Failed to connect (check the URL or package name), ⏸ Pending approval (run claude interactively and accept it). For one server’s full detail:
claude mcp get notion
Common Mistakes to Avoid
-
Forgetting the
--separator on stdio servers. Without it, Claude Code can’t tell where its own flags end and the server’s launch command begins. -
Hardcoding API keys directly in the URL or command. Use
--headeror--envinstead, so secrets aren’t sitting in your shell history or a committed.mcp.json. -
Assuming a listed server is actually working. A server appears in
claude mcp listas soon as it’s configured — always check the status column, don’t assume “listed” means “connected.” -
Not restarting after adding a server. Claude Code needs a fresh session (or the
/mcppanel refresh) to pick up a newly added server. -
Ignoring a pending-approval status. Project-scoped servers from a teammate’s
.mcp.jsonsit unapproved until you runclaudeinteractively and accept the prompt.
Q&A
What’s the difference between user scope and project scope?
User scope is private to you and active in every project. Project scope lives in .mcp.json in the repo, so it’s shared with anyone who clones it — useful for team-standard tools.
Do I need to know how to code to use MCP servers?
No. Adding one is a single CLI command, and once connected, Claude Code calls its tools automatically when relevant — no manual invocation required.
Can I just have the agent do the whole setup?
Yes — that’s what the copy-paste prompt above is for. Claude Code can run its own claude mcp commands in a session, so it can add a server and re-check the connection itself instead of you typing each command.
Can I remove a server later?
Yes — claude mcp remove <name> deletes it from config, and for remote servers it also clears any stored OAuth tokens.
Why does a server show “Failed to connect”?
Usually a wrong URL, a missing auth header, or the local package failing to start. Run claude mcp get <name> for the specific error before troubleshooting further.
Official Resources
- Claude Code MCP Documentation — full command reference and transport options
- MCP Quickstart — official getting-started walkthrough
- Model Context Protocol — the open spec MCP servers implement
Originally published at quickpromptco.com, where the guide is kept up to date.
Top comments (0)