How to add an MCP server to Claude Code in 5 minutes (with examples)

The 5-minute version

You can add an MCP server to Claude Code with one CLI command:

claude mcp add <name> <command> [args...]

For example, to add agentmako (an open-source MCP server for codebase context):

claude mcp add mako-ai agentmako mcp

Restart Claude Code, run /mcp inside the session, confirm the server shows as connected. Done.

The rest of this post explains what's actually happening, the alternative methods, common errors, and a few useful MCP servers to pair with Claude Code.

What is MCP and why does Claude Code use it?

The Model Context Protocol is an open standard from Anthropic (released November 2024) that lets AI agents call external tools via a stdio JSON-RPC interface. Think of it as "USB for AI agents" — one protocol, every tool plugs in.

Claude Code uses MCP as its primary extensibility mechanism. Want Claude Code to read your database? Add an MCP server for it. Want it to query Linear? Add an MCP server. Want it to understand your codebase deeply? Add one for that.

Servers are processes Claude spawns when needed. Each server exposes a list of tools with typed schemas. Claude decides when to call which tool based on what you're asking.

Three ways to add an MCP server

Method 1: CLI (recommended)

Claude Code 2.x ships with claude mcp subcommands:

claude mcp add <name> <command> [args...]    # add a server
claude mcp list                              # list configured servers
claude mcp remove <name>                     # remove

Example:

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

This adds a filesystem MCP server scoped to /Users/me/projects. Restart Claude Code (full quit + reopen), and inside a session, /mcp will show the new server with green status.

Method 2: Edit ~/.claude.json directly

If you want full control or a more complex configuration:

{
  "mcpServers": {
    "mako-ai": {
      "command": "agentmako",
      "args": ["mcp"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

The file lives at:

• macOS / Linux: ~/.claude.json
• Windows: %USERPROFILE%\.claude.json

Save, fully restart Claude Code.

Method 3: Project-scoped .mcp.json

For per-project servers (only loaded when you're working in that directory), create .mcp.json at the project root:

{
  "mcpServers": {
    "mako-ai": {
      "command": "agentmako",
      "args": ["mcp"]
    }
  }
}

This is the right place for codebase-specific tools. agentmako, for example, only makes sense in projects you've attached it to — .mcp.json keeps it scoped.

Verifying it works

After adding a server and restarting, run /mcp inside Claude Code:

/mcp

mako-ai      ✓ connected   34 tools
filesystem   ✓ connected   11 tools
github       ✗ failed      check token

Green = working. Red = something's wrong. Click (or hover) to see the error.

You can also expand a server to see the full list of tools it exposes. They appear inside Claude Code conversations as mcp__<server-name>__<tool-name> — for example, mcp__mako-ai__context_packet.

Common errors

"command not found"

The most common failure. Claude Code can't find the server's executable on PATH.

Fix:

1. Confirm it's installed globally: which agentmako (or where on Windows). If empty, the install failed.
2. Re-run the install: npm install -g agentmako.
3. Fully quit Claude Code and reopen. PATH gets cached at launch.

If which shows the binary but Claude Code still can't find it, it's a PATH inheritance issue. Try setting the absolute path in ~/.claude.json:

{
  "mcpServers": {
    "mako-ai": {
      "command": "/usr/local/bin/agentmako",
      "args": ["mcp"]
    }
  }
}

"server failed to start"

Run the server manually in a terminal:

agentmako mcp

Whatever stack trace you see is the same thing breaking inside Claude Code. Most common causes:

• The tool requires environment variables you didn't set.
• The tool requires a project to be attached (run agentmako connect . first).
• A port conflict (some MCP servers bind a local socket).

Tools show as connected but Claude doesn't call them

Two possibilities:

1. Claude doesn't know to call them. The agent's tool-selection is conservative by default. Either prompt explicitly ("use the mako-ai context_packet tool first") or add instructions to your CLAUDE.md telling it when to use which tool.
2. The tool descriptions are vague. If you wrote the MCP server, the tool descriptions matter. Claude reads them when deciding what to call. "Returns context" is too vague; "Returns ranked file paths and line numbers for a coding task description" is precise.

A short list of useful MCP servers for Claude Code

These are the ones I keep installed across projects:

agentmako — codebase context engine

What it does: indexes your repo into local SQLite and exposes typed tools for code intelligence (file ranking, route tracing, schema awareness, durable findings).

Install:

npm install -g agentmako
agentmako connect /path/to/your/project --no-db
claude mcp add mako-ai agentmako mcp

Apache-2.0, local-first, no hosted service. agentmako.drhalto.com

@modelcontextprotocol/server-filesystem — scoped file access

What it does: gives Claude controlled access to a specific directory tree. Useful when you want Claude to read/write outside the current project root.

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

@modelcontextprotocol/server-github — GitHub API

What it does: lets Claude search issues, read PRs, comment, create branches.

claude mcp add github npx @modelcontextprotocol/server-github

Requires a GITHUB_PERSONAL_ACCESS_TOKEN env var.

@modelcontextprotocol/server-postgres — direct DB queries

What it does: lets Claude run SQL against a Postgres connection.

⚠️ Caution: this gives Claude direct DB access. Use a read-only connection unless you really know what you're doing. Or use agentmako's db_table_schema / db_rls tools instead, which are read-only by default.

The Claude Code plugin system (next level)

In late 2025, Claude Code added a plugin system on top of MCP. A plugin is an MCP server bundled with skills — Claude-specific instruction files that tell the agent when to call which tool.

If you're authoring an MCP server, shipping it as a Claude Code plugin gives you better default behavior. The skills tell Claude: "for code-search questions, call my find_references tool first; for refactoring, call imports_impact first."

agentmako ships as both a bare MCP server AND a Claude Code plugin (mako-ai). The plugin path adds 8 skills (mako-guide, mako-discovery, mako-trace, mako-graph, mako-database, mako-code-intel, mako-workflow, mako-neighborhoods). For Claude Code specifically, the plugin path is better — the agent picks tools more accurately because it has guided instructions.

Putting it together

For most devs the high-leverage stack inside Claude Code is:

1. agentmako for codebase + DB context (one install, every project).
2. filesystem-mcp for cross-project file access.
3. github-mcp if you live in PRs.
4. Whatever vertical tool fits your domain — Linear, Slack, Notion, etc.

Start with one. Get comfortable with /mcp and watching what tools Claude actually calls. Add more as the gaps become obvious.

The MCP ecosystem is growing fast — new servers ship weekly on Smithery and Glama. Worth checking those directories monthly to see what's appeared.

Further reading

• agentmako Claude Code setup guide — full walkthrough including the plugin path
• agentmako CLAUDE.md template — drop into your project root to teach Claude when to use which tool
• MCP spec — if you want to write your own server
• Smithery and Glama MCP directory — discover community MCP servers