Claude Code MCP Servers: Add Real Tools in Minutes

TL;DR

The Model Context Protocol (MCP) lets Claude Code reach tools and data outside your repo: databases, GitHub, monitoring, design files. You register a server once with claude mcp add, pick a transport (http for remote services, stdio for local processes) and a scope (local, project, or user), then Claude calls its tools as mcp__servername__toolname. Start with one server, prove it saves a manual copy-paste, then add more. If you just want the commands, jump to the step-by-step below; if you want the picks, see “The first servers worth installing”.

What this covers

How to actually plug MCP servers into Claude Code — not what MCP is in the abstract, but the concrete claude mcp add flow, the three transports (stdio, http, sse), the scope flags (local vs project vs user), and which servers are worth installing on day one. The common failure: people read the MCP spec, get excited, install five servers at once, hit a permission prompt every few seconds, and turn the whole thing off. This guide installs one server, gets it working, then shows how to add more without that friction.

Key concepts:

• MCP (Model Context Protocol): Anthropic’s open standard for exposing tools, files, and data to an LLM. It is now supported across Claude Code, Claude Desktop, Cursor, and many other clients.
• claude mcp add: the CLI subcommand that registers a server with your Claude Code install.
• Transports: stdio (local subprocess, for tools that run on your machine), http (streamable HTTP, the recommended transport for remote/cloud services), and sse (older HTTP server-sent events, now deprecated in favor of http).
• Scopes: local (current project only, private to you — the default), project (committed to the repo in .mcp.json, shared with the team), user (all your projects, private to you).
• Tool naming: registered tools appear as mcp__servername__toolname in Claude Code’s tool list.

Who this is for

Claude Code users who have finished the beginner guide and want to stretch the agent past reading and editing files. Especially if you spend time pasting database query results, GitHub PR comments, or Sentry stack traces into chat — those are exactly the integrations MCP eliminates.

When to reach for it

When the same “copy from another tool, paste into chat” step happens twice in a session. Database lookups, GitHub PR comments, error logs, design specs, filesystem access outside the repo — each is a candidate for an MCP server. Don’t add MCP servers preemptively; add one when you’ve caught yourself doing the manual step. The official docs put it the same way: connect a server when you find yourself copying data into chat from another tool.

Pick the right transport and scope first

Two decisions up front save most of the confusion. Which transport, and which scope.

Transport	Use it for	How Claude reaches it	Status (June 2026)
stdio	Local tools and scripts (filesystem, a local database client, a custom Python server)	Spawns a subprocess and talks over stdin/stdout	Stable, default for local servers
http	Remote/cloud services (GitHub, Sentry, Notion, Stripe)	Connects to a URL, supports OAuth and Bearer headers	Recommended for all remote servers
sse	Legacy remote servers that only offer SSE	Connects to an SSE URL	Deprecated — use http where the server offers it

Scope	Loads in	Shared with team	Stored in
local (default)	Current project only	No	~/.claude.json (under the project path)
project	Current project only	Yes, via version control	.mcp.json at the repo root
user	All your projects	No	~/.claude.json

Two naming notes, because older guides and screenshots disagree: what is now --scope local used to be called project, and what is now --scope user used to be called global. If you see those older flag names, mentally remap them. And precedence runs local > project > user, so a local override wins over a shared project entry of the same name.

Before you start

• Claude Code installed and working (claude --version). If not, see the beginner guide.
• Node 18+ on PATH — most reference stdio servers run via npx.
• For project-scoped servers, a git repo where you’re comfortable committing .mcp.json.
• The credentials for whatever you’re connecting (a GitHub fine-grained PAT, a Postgres connection string). Don’t start the install until you have them.

Step by step

1. List currently registered servers so you know the starting state:

claude mcp list

2. Add the filesystem reference server. Scope it to user so it’s available in every project. It exposes read/write tools for a specific directory:

claude mcp add filesystem --scope user \
  -- npx -y @modelcontextprotocol/server-filesystem ~/work

The -- separator is required: everything after it is the command Claude Code spawns over stdio. Without --, Claude Code tries to parse the server’s own flags as its own options and the registration fails.

3. Reload in Claude Code by running /mcp in chat (or restart the session). Confirm the server is connected:

claude mcp list
# filesystem: ... - ✓ Connected

4. Try a tool. In Claude Code, ask: List the files in ~/work using the filesystem tool. Claude requests permission the first time — for read-only tools you can choose “always allow” so you aren’t prompted on every call.

5. Add a remote service over HTTP. GitHub is the highest-value one for most developers. As of June 2026 the old @modelcontextprotocol/server-github npm package is deprecated; GitHub now ships an official remote server you connect over HTTP with a fine-grained personal access token:

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

Generate the token at GitHub Settings → Developer settings → Fine-grained tokens, scoped to only the repos you want Claude to touch. For servers that use OAuth instead of a token (Sentry, Notion, Linear), skip the header and run /mcp in chat to complete the browser login.

6. Add a project-scoped server your teammates should share — a read-only database connection is the classic case. This writes a .mcp.json at the repo root:

claude mcp add db --scope project \
  -- npx -y @bytebase/dbhub --dsn "$DATABASE_URL"

Verify it shows in claude mcp list with project scope and that .mcp.json exists at the repo root. Commit .mcp.json; keep the actual connection string in an environment variable, not inlined (see the config template below).

7. When a server misbehaves, debug in this order: claude mcp list (is it registered and connected?) → claude mcp get servername (what command or URL?) → run /mcp in chat to check live status and re-authenticate. If a remote server disconnects mid-session, Claude Code retries automatically with exponential backoff (up to five attempts); stdio servers are local processes and are not auto-reconnected. For persistent disconnects see Claude MCP server disconnect.

The first servers worth installing

Three servers cover most of the daily paste-into-chat pain. Resist adding a fourth until you’ve lived with these for a week.

Server	Transport	Kills this manual step	Install
filesystem	stdio	Pasting logs and files from outside the repo	npx -y @modelcontextprotocol/server-filesystem <dir>
GitHub	http	Pasting PR comments, issues, and diffs	remote https://api.githubcopilot.com/mcp/ + PAT
database (dbhub)	stdio	”Let me check the schema” copy-pastes	npx -y @bytebase/dbhub --dsn <connection-string>

Why these three: filesystem lets the agent reach files outside the current repo (logs, scratch dirs). GitHub kills the “paste PR comments into chat” loop. The database server turns “let me check what the schema looks like” from a paste into a query. (@bytebase/dbhub is the current maintained replacement for the deprecated @modelcontextprotocol/server-postgres, and it speaks Postgres, MySQL, SQL Server, MariaDB, and SQLite.)

One more worth knowing about: @playwright/mcp (stdio) gives Claude a real browser to test flows and take screenshots, which is handy for front-end work:

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

Config template for the three

If you’d rather edit JSON directly than run three claude mcp add commands, this is a .mcp.json for the project scope. Note that secrets are referenced as environment variables, never inlined — Claude Code expands ${VAR} (and ${VAR:-default}) at load time:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${CLAUDE_PROJECT_DIR:-.}"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    }
  }
}

Each developer sets GITHUB_PAT and DATABASE_URL in their own environment, so the committed file carries no secrets. Project-scoped servers prompt every teammate for approval the first time they open the repo — that’s the security model, not a bug.

Quality check

• claude mcp list shows each server as connected, not error, disconnected, or ⏸ Pending approval.
• Tools appear in chat with the mcp__servername__toolname naming — ask “what tools do you have” and Claude lists them.
• Permission prompts make sense: read-only tools auto-allowed after the first approval, write tools always prompt.
• .mcp.json is committed but secrets stay in environment variables, not inlined.
• The agent actually uses the MCP tools without being told to. If it keeps asking you to paste database results despite a live DB server, name the tool explicitly the first few times: “use the db tool to query…”.

Reuse this across projects

• Keep your everyday, machine-wide servers at user scope — filesystem and a personal GitHub connection are good candidates. They follow you into every project.
• For each repo, commit a minimal .mcp.json (project scope) with project-specific servers: that project’s database, its issue tracker if it has an MCP.
• Document MCP usage in CLAUDE.md: “When investigating database issues, use the db MCP.” Explicit instructions help Claude pick the right tool on the first turn.
• Evaluate a newly popular server at local scope solo before sharing it at project scope. Buggy servers waste the whole team’s time.

The loop in one line: notice a manual paste → find an MCP server for that data → claude mcp add with the right transport and scope → verify with claude mcp list → name the tool explicitly the first few times → settle into automatic use.

Common mistakes

• Installing five servers on day one. Permission fatigue kills the experiment. Start with one, prove value, then add another.
• Putting secrets directly in .mcp.json and committing it. Reference ${VAR} from your environment; keep the real values in .env (which stays untracked).
• Forgetting the -- separator in a stdio claude mcp add. The command after it gets parsed as flags and registration fails.
• Using --scope local for a server teammates need. Local scope isn’t shared; use project for repo-wide servers, user for personal cross-project ones.
• Reaching for the deprecated npm packages. @modelcontextprotocol/server-github and @modelcontextprotocol/server-postgres are no longer maintained — use GitHub’s remote HTTP server and @bytebase/dbhub instead.
• Letting a disconnected server sit. Either fix it or remove it with claude mcp remove. Dead servers clutter the tool list (disconnect troubleshooting).

FAQ

• Do I need MCP at all if I’m just editing code? No. MCP reaches outside the codebase — databases, APIs, external files. Pure code editing works fine with Claude Code’s built-in tools.
• Which transport should I pick? stdio for anything that runs locally (filesystem, a local DB client, your own script). http for any remote/cloud service, because it supports OAuth and Bearer headers. Only use sse if a remote server offers nothing else, since SSE is deprecated.
• What’s the default scope? local — the server loads only in the current project and stays private to you, stored in ~/.claude.json. Use project to share via .mcp.json, or user to make it available across all your projects.
• How do I authenticate a remote server that needs OAuth? Add it with claude mcp add --transport http, then run /mcp in chat and follow the browser login. Tokens are stored securely and refreshed automatically.
• Can I write my own MCP server? Yes. The protocol is open with official Python and TypeScript SDKs, and Claude Code can scaffold one for you via the mcp-server-dev plugin (/mcp-server-dev:build-mcp-server).
• Do MCP servers work in Cursor too? Yes. The protocol is shared, so the same servers work, but the registration UI differs from Claude Code’s CLI.

Related

• Claude Code beginner guide
• Claude Code project setup
• Claude MCP server disconnect
• Claude Code slash commands

External references: Claude Code MCP docs · Model Context Protocol

Tags: #AI coding #Tutorial #Claude Code

Related Articles

AI Tool Tutorials

AI Changelog Generation: From Commits to a Release Note Humans Read

Turn git log into a two-tier release note readers actually finish, with a review pass that catches buried breaking changes.

May 24, 2026 #AI coding #Workflow

AI Tool Tutorials

AI-Assisted Database Migrations — Reversible, Backfilled, Tested

The three things AI gets wrong on migrations: reversibility, backfill, and the NOT NULL on a big table.

May 24, 2026 #AI coding #Workflow

AI Tool Tutorials

AI for Incident Postmortems Without Sanitizing the Lessons

A step-by-step workflow to draft a blameless postmortem with AI in 60 minutes without letting the model round off the uncomfortable truths.

May 24, 2026 #AI coding #Workflow

AI Tool Tutorials

AI Merge Conflict Resolution: When to Trust the Auto-Merge

AI clears most git merge conflicts in minutes. The workflow is knowing which 10% it must never touch — and how to catch the 'merged by deleting one side' failure.

May 24, 2026 #AI coding #Workflow

AI Tool Tutorials

AI On-Call Debugging: From Page to Fix Without Panic

Get paged at 3am? A tested AI workflow for triage, hypothesis ranking, a calm-down protocol before destructive commands, and turning the chat into a runbook.

May 24, 2026 #AI coding #Workflow

AI Tool Tutorials

AI PR Descriptions: From Diff to Reviewable

Turn a git diff into a PR body a reviewer will actually read, with prompts that don't invent test plans for tests that don't exist. Verified workflow, June 2026.

May 24, 2026 #AI coding #Workflow