Claude Code MCP — How to Connect Servers and Add Tools to Claude

A Claude Code conversation can only do so much with the tools shipped in the box. The moment you want Claude to touch Notion, Stripe, your AWS account, a specific database — you need MCP.

MCP (Model Context Protocol) is the standard that connects Claude to external tools. Here's what it is, how to add servers, and the patterns that don't waste your time.

What MCP actually is

MCP is an open protocol. A small server process (the "MCP server") exposes a set of tools. Claude Code (the "MCP client") talks to it over stdio or HTTP. When Claude needs to call one of those tools, it sends a JSON-RPC request; the server runs the function and returns the result.

Three pieces:

• MCP server — the process that exposes tools. Usually npx-installable. Examples: filesystem, GitHub, Notion, Stripe, Postgres.
• MCP client — Claude Code itself. It manages connections, surfaces tools to the model, routes calls.
• Tool — a single callable function the server exposes (e.g. read_file, create_pr, search_pages).

The model doesn't know or care what the server is doing internally. It just sees a tool with a JSON schema and calls it like any other.

How to add an MCP server

The CLI takes care of registration.

claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /Users/me/projects

Format: claude mcp add <local-name> <command...>.

What happens:

1. Claude Code writes the entry to your global MCP config (~/.claude/mcp.json)
2. On next session start, Claude spawns the subprocess
3. The server advertises its tools at handshake
4. Claude registers them under a prefixed namespace (mcp__filesystem__read_file)

The model then has access to those tools the same way it has access to built-in ones.

Listing and removing servers

claude mcp list             # shows registered servers + status + tool count
claude mcp remove filesystem # unregister

If list shows a server as disconnected, the subprocess failed. The most common cause is a typo in the command or a missing argument. Check the command, fix it (remove + re-add), restart your session.

Project-scoped MCP

For team workflows where everyone needs the same servers, put an mcp.json in .claude/ inside the repo. Format:

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

Project-level config overrides global. Anyone who clones the repo and starts Claude Code in it gets the same servers automatically — no per-machine setup.

MCP servers worth installing first

Start with three. Add others as your workflow demands them.

1. Filesystem — @modelcontextprotocol/server-filesystem. Lets Claude read/write files outside the current working directory. Essential for cross-repo work and templated setup.

2. GitHub — @modelcontextprotocol/server-github. PR/issue management without leaving the CLI. Combined with a slash command for shipping, this becomes one of the highest-leverage installs.

3. Your ticket system — Notion, Linear, Jira, depending on where your work tracking lives. Even read-only access here turns "what did I commit to this sprint?" into a one-line question.

After those, install what your daily workflow actually touches. If you don't use Stripe daily, don't install the Stripe server. The cost isn't zero — every connected server takes startup time and adds tools that show up in the model's view.

MCP vs Skills — they compose

People sometimes ask whether to build a workflow as a Skill or an MCP server. They're different layers and they compose.

• MCP server: provides a capability ("Stripe data is accessible")
• Skill: orchestrates a workflow ("monthly revenue check — pull from Stripe, format, paste into Notion")

The skill calls the MCP server's tools. Without the server, the skill can't reach Stripe. Without the skill, the server's tools are there but you'd have to write the workflow each time.

Build MCP servers when you need to expose data or actions. Build Skills when you need to capture a repeated workflow.

Debugging an MCP server

When something doesn't work:

1. Check status: claude mcp list — is it disconnected?
2. Check the command: typos, missing arguments, wrong path
3. Check env vars: many servers need API keys; missing them silently break the connection
4. Run the server manually: in a separate terminal, run the exact command you registered. If it crashes, the error message is right there
5. Check the server's own logs: most log to stderr with helpful detail. Claude Code surfaces these at session start

Most MCP issues are infrastructure (env var, path, subprocess), not protocol. The protocol itself is stable.

Remote MCP servers

Newer transports (SSE, HTTP) let an MCP server run anywhere — your laptop, an internal box, a hosted service. For solo work, stdio (subprocess) is simpler. For teams, a remote MCP server can expose internal tools (databases, dashboards, deployment APIs) to every engineer without each having to install a local process.

The tradeoffs: remote is harder to debug (network in the middle), but easier to update centrally.

The actual payoff

The point of MCP isn't the protocol — it's that you stop copying values between tabs. Notion data flows into Claude. Claude writes back to GitHub. Stripe metrics land in your daily check. Each connection saves a context switch you used to do dozens of times a day.

Install three servers. Use them for a week. You'll know which ones to keep and which to drop.

Related: Claude Code Skills — workflows you reuse · Claude Code Agents · Claude Code Subagents · Claude Code Plan Mode · Connect Claude to Notion, Gmail and Drive