Claude Code MCP Setup: A Step-by-Step Guide

MCP is how Claude Code discovers external tools. Get the setup right and your agent gains capabilities like web search, image generation, and email. Get it wrong and the tools don’t show up. This guide covers everything from first principles to fixing the common snags.

What MCP Does

The Model Context Protocol is a standard for connecting AI agents to external tool servers. Each MCP server exposes one or more tools, each with a name, description, and input schema. When Claude Code starts, it queries every configured MCP server and registers the available tools. From that point on, the agent can call those tools during your session, choosing when and how to use them based on the task.

You don’t write glue code. You don’t import libraries. You add a server to your config, and the tools appear.

The claude mcp add Command

The fastest way to add an MCP server is the built-in CLI command:

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

This writes the server config to your Claude Code settings. A few real examples:

# Add a local MCP server
claude mcp add my-server -- node /path/to/server.js

# Add a server with environment variables
claude mcp add my-server -e API_KEY=sk-abc123 -- npx my-mcp-package

The -e flag passes environment variables to the server process. Useful for API keys and auth tokens.

Config File Locations

Claude Code stores MCP config in JSON files at two levels:

  • Project-level: .claude/settings.json in your project root. Tools here are available when you’re working in that project.
  • User-level: ~/.claude/settings.json. Tools here are available in every project.

The config looks like this:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["my-mcp-package"],
      "env": {
        "API_KEY": "sk-abc123"
      }
    }
  }
}

Each key under mcpServers is a server name. The command and args fields define how to start the server process. The env field is optional.

Verifying Tools Loaded

After adding a server, start a Claude Code session and run /mcp. This shows all connected MCP servers and their status. You should see your server listed with its tools.

You can also ask Claude Code to list its available tools. If the MCP server connected, the tools will appear in the list.

Troubleshooting

Server not connecting: The most common cause is a bad command path. Make sure the command (node, npx, python, etc.) is on your PATH and that the server script or package exists. Run the command manually in your terminal to verify it starts.

Tools not appearing: The server might be starting but not responding to the MCP discovery call. Check that your server implements the tools/list method. Some servers need a moment to initialize: try restarting Claude Code.

Environment variables not reaching the server: Double-check the env block in your config. Variable names are case-sensitive. If you’re using claude mcp add, pass each variable with a separate -e flag.

“Server disconnected” errors mid-session: The server process crashed. Check its logs (stderr output goes to Claude Code’s debug log). Common causes: unhandled exceptions, the server running out of memory, or a dependency not being installed.

AgentPatch as an Example MCP Server

AgentPatch is a managed MCP service that bundles multiple tools (web search, image generation, email, maps, news, and more) behind one server. It’s a good way to test your MCP setup because one config entry gives you many tools to verify.

The AgentPatch CLI is designed for AI agents to use via shell access. Install it, and your agent can discover and invoke any tool on the marketplace.

Install (zero dependencies, Python 3.10+):

pip install agentpatch

Set your API key:

export AGENTPATCH_API_KEY=your_api_key

Example commands your agent will use:

ap search "web search"
ap run google-search --input '{"query": "test"}'

Get your API key from the AgentPatch dashboard.

Install the AgentPatch skill — it teaches Claude Code when to use AgentPatch and how to use the CLI:

/plugin marketplace add fullthom/agentpatch-claude-skill
/plugin install agentpatch@agentpatch

MCP Server (Alternative)

If you prefer raw MCP tool access instead of the skill:

claude mcp add -s user --transport http agentpatch https://agentpatch.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with your actual key from the AgentPatch dashboard.

After adding this, run /mcp in Claude Code. You should see the AgentPatch server with its full tool list. If the tools appear, your MCP setup is working.

Wrapping Up

MCP setup in Claude Code comes down to three things: a working server command, the right config file, and valid environment variables. Once that’s in place, tool discovery is automatic. AgentPatch is one way to get a bundle of tools through a single config entry. Browse available tools at agentpatch.ai.

← Back to blog