AI AI Tools Guidebook
AI Tool Tutorials

Claude Code MCP Servers — Wiring Up Real Tools

What MCP is, how to add a server with claude mcp add, three transport types, and the first servers worth installing.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

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 transport types (stdio, sse, http), the scope flags (user vs project vs local), and which servers are worth installing on day one. The pain: people read the MCP spec, get excited, install five servers at once, hit permission prompts every five seconds, and turn the whole thing off. This guide picks one server, gets it working, then explains how to add more without that friction.

Key concepts:

  • MCP (Model Context Protocol): Anthropic’s open protocol for exposing tools, files, and data to an LLM.
  • claude mcp add: the CLI subcommand to register a server with your Claude Code install.
  • Transports: stdio (local subprocess, default), sse (HTTP server-sent events), http (streamable HTTP).
  • Scopes: --scope user (your machine), --scope project (committed to repo), --scope local (current dir, not shared).
  • Tool naming: registered tools appear as mcp__servername__toolname in Claude Code’s tool list.

Who this is for

Claude Code users who have done the beginner guide and want to stretch what the agent can do beyond reading and editing files. Especially if you spend time pasting database query results, GitHub issue text, or Slack threads into the chat — those are exactly the integrations MCP eliminates.

When to reach for it

When the same context-paste-from-another-tool happens twice in a session. Database lookups, GitHub PR comments, Slack search, filesystem access outside the repo — each is a candidate for an MCP server. Don’t add MCP servers preemptively; add them when you’ve noticed yourself doing the manual step.

Before you start

  • Claude Code installed and working (claude --version). If not, see the beginner guide.
  • Node 18+ on PATH — most reference MCP servers run via npx.
  • For project-scoped servers, a git repo where you’re comfortable committing the .mcp.json config.
  • The credentials for whatever you’re connecting (Postgres URL, GitHub token, Slack token) — 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
  1. Add the filesystem reference server scoped to your user (works everywhere). 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 will spawn over stdio.

  1. Restart your Claude Code session (or run /mcp in chat to reload). Confirm the server is listed:
claude mcp list
# Expected: filesystem (stdio) - user scope - ok
  1. Try a tool. In Claude Code, ask: List files in ~/work using the filesystem tool. Claude will request permission the first time — accept once per tool, not per call (use the “always allow” option if available for read-only tools).
  2. Add a project-scoped server you want teammates to share. Postgres is a common one — it commits a .mcp.json to the repo:
claude mcp add postgres --scope project \
  --env DATABASE_URL=$DATABASE_URL \
  -- npx -y @modelcontextprotocol/server-postgres
  1. Verify it shows in claude mcp list with project scope, and that .mcp.json was created at the repo root. Commit .mcp.json but not any .env with secrets.
  2. When a server misbehaves, debug in this order: claude mcp list (is it registered?), claude mcp get servername (what command?), then check Claude Code’s logs (usually ~/.claude/logs/ on macOS/Linux). If it disconnects mid-session, see Claude MCP server disconnect.

A config that produces honest output

The first three MCP servers worth installing, with reasoning. Save this as a .mcp.json template:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/work"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgres://localhost/myapp_dev" }
    }
  }
}

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. Postgres turns “let me check what the schema looks like” from a paste into a query. Don’t add a fourth until you’ve used these for a week.

Quality check

  • claude mcp list shows each server as ok, not error or disconnected.
  • Tools appear in chat with the mcp__servername__toolname naming — if you ask “what tools do you have” Claude lists them.
  • Permission prompts make sense: read-only tools auto-allowed after the first prompt, write tools always prompt.
  • .mcp.json is committed but secrets are in env vars, not inlined.
  • The agent actually uses the MCP tools without being told to. If it keeps asking you to paste database results despite a Postgres MCP being live, your prompt isn’t naming the tool — say “use the postgres tool to query…” explicitly the first few times.

How to reuse this workflow

  • Maintain a personal ~/.claude/mcp-user.json (or whatever the user scope file is called) with your everyday user-scope servers — filesystem, GitHub.
  • For each project, commit a minimal .mcp.json with project-specific servers (the project’s database, the project’s tracker if it has an MCP).
  • Document the project’s MCP usage in CLAUDE.md: “When investigating database issues, use the postgres MCP” — explicit instructions help Claude pick the right tool.
  • When a new MCP server gets popular, evaluate it solo first before sharing with the team. Buggy servers waste everyone’s time.

Notice manual paste → find an MCP server for that data → claude mcp add with the right scope → verify with claude mcp list → use 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. Use env vars referenced from .mcp.json, keep the actual values in .env.
  • Forgetting the -- separator in claude mcp add — the command after it gets parsed as flags and the server registration fails silently.
  • Using --scope local for a server teammates need. Local scope isn’t shared; use project for repo-wide servers.
  • Ignoring transport choice. Stdio is fastest and simplest for local servers; only reach for sse/http when the server actually runs as a separate process you didn’t spawn.
  • Letting a disconnected server sit. Either fix it or remove it (claude mcp remove). Disconnected servers clutter the tool list and confuse the model (MCP server disconnect troubleshooting).

FAQ

  • Do I need MCP at all if I’m just editing code?: No. MCP is for reaching outside the codebase — databases, APIs, external files. Pure code editing works fine without it.
  • Can I write my own MCP server?: Yes, the protocol is open and there are SDKs in Python and TypeScript. The reference servers are good templates.
  • What’s the difference between MCP and Claude Code’s built-in tools?: Built-in tools (read, write, bash, etc.) are baked into the agent. MCP tools are pluggable — your servers, your transport, your auth.
  • Do MCP servers work in Cursor too?: Cursor supports MCP as well, with its own UI. The protocol is shared, the registration flow is different.

Tags: #AI coding #Tutorial #Claude Code

Related Articles