# How to use MCP with Claude Code

- Tool: MCP
- Difficulty: Intermediate
- Time required: 10 min
- Compatibility: Claude Code CLI, any MCP server
- Last updated: March 2026

## TL;DR

Claude Code (Anthropic's CLI tool) supports MCP servers through the claude mcp add command or by editing the project-level .mcp.json file. Servers can be added at project scope (shared via git) or user scope (personal). Claude Code runs MCP servers as child processes and makes their tools available during coding sessions. Use claude mcp list to see connected servers and claude mcp remove to disconnect them.

## Use MCP Servers with Claude Code CLI

Claude Code is Anthropic's terminal-based AI coding assistant. Unlike GUI-based hosts, Claude Code manages MCP servers through CLI commands. You add servers with claude mcp add, list them with claude mcp list, and remove them with claude mcp remove. Servers can be scoped to a project (stored in .mcp.json, shareable via git) or to a user (stored in your home directory). During coding sessions, Claude Code autonomously uses MCP tools as part of its agentic workflow.

## Before you start

- Claude Code CLI installed (npm install -g @anthropic-ai/claude-code or similar)
- An MCP server to connect (npm package, local server, or Docker image)
- A terminal/shell environment
- Basic command-line familiarity

## Step-by-step guide

### 1. Add an MCP server using the CLI

Use the claude mcp add command to register an MCP server. Provide a name for the server followed by the command and arguments to launch it. By default, servers are added at project scope, meaning they are stored in the project's .mcp.json file.

```
# Add the filesystem MCP server
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

# Add a custom TypeScript server
claude mcp add my-server -- npx -y tsx /path/to/server/src/index.ts

# Add a Python server
claude mcp add python-server -- uv run --directory /path/to/server server.py
```

**Expected result:** The server is registered and will be available in your next Claude Code session.

### 2. Add servers with environment variables

Use the -e flag to pass environment variables to the MCP server. This is essential for servers that need API keys or connection strings. You can pass multiple -e flags for multiple variables.

```
# Add Brave Search server with API key
claude mcp add brave-search -e BRAVE_API_KEY=your-key -- npx -y @modelcontextprotocol/server-brave-search

# Add GitHub server (Docker) with token
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

# Add a server with multiple env vars
claude mcp add database -e DB_HOST=localhost -e DB_PASSWORD=secret -- npx -y tsx /path/to/db-server/src/index.ts
```

**Expected result:** The server is registered with its environment variables stored securely.

### 3. Choose between project scope and user scope

By default, servers are added at project scope (stored in .mcp.json in your project directory, shareable via git). Use the -s user flag to add servers at user scope (stored in your home directory, available across all projects). Project scope is best for project-specific servers, user scope for personal tools like filesystem or search.

```
# Project scope (default) — stored in .mcp.json, team-shareable
claude mcp add project-db -- npx -y tsx /path/to/project/db-server.ts

# User scope — available in all projects, personal
claude mcp add -s user filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you
claude mcp add -s user brave-search -e BRAVE_API_KEY=key -- npx -y @modelcontextprotocol/server-brave-search
```

**Expected result:** Project-scope servers appear in .mcp.json; user-scope servers are stored globally.

### 4. List and manage configured servers

Use claude mcp list to see all configured servers (both project and user scope). Use claude mcp remove to disconnect a server. These commands help you audit and maintain your MCP setup.

```
# List all configured MCP servers
claude mcp list

# Remove a server
claude mcp remove my-server

# Remove a user-scope server
claude mcp remove -s user filesystem
```

**Expected result:** You can see all connected servers and remove ones you no longer need.

### 5. Edit .mcp.json directly for advanced configuration

For complex setups or to share configuration with your team, you can edit the .mcp.json file directly. This file is created automatically by claude mcp add but can also be hand-edited. The format uses mcpServers as the top-level key, similar to Claude Desktop.

```
// .mcp.json (in project root)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"],
      "env": {}
    },
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    }
  }
}
```

**Expected result:** A hand-edited .mcp.json file with multiple servers configured.

### 6. Use MCP tools during a Claude Code session

Start a Claude Code session with claude or claude chat. Claude Code automatically connects to all configured MCP servers. During the session, Claude can autonomously call MCP tools as part of its coding workflow. For example, it might use a database server to check schema before writing queries, or a GitHub server to read issue details. For teams building complex agentic workflows, RapidDev can help design MCP integrations that maximize Claude Code's effectiveness.

```
# Start a Claude Code session
claude

# Or start with a specific task
claude "Check the open GitHub issues and create a summary"
```

**Expected result:** Claude Code uses MCP tools autonomously as part of its agentic coding workflow.

## Complete code example

File: `.mcp.json`

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ],
      "env": {}
    },
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {}
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}
```

## Common mistakes

- **Forgetting the -- separator before the server command** — undefined Fix: The claude mcp add command uses -- to separate the MCP server name/flags from the actual server command. Without it, the server command arguments are interpreted as claude flags.
- **Adding secrets to project-scope .mcp.json and committing to git** — undefined Fix: Be careful with project-scope servers that have API keys in the env field. Either add .mcp.json to .gitignore, or use user-scope for servers with secrets, or use environment variable references.
- **Not using -y flag in npx commands** — undefined Fix: Claude Code spawns server processes non-interactively. Without -y, npx prompts for installation confirmation and the server hangs. Always include -y in npx commands.
- **Confusing project and user scope** — undefined Fix: Project scope (default) stores config in .mcp.json in the current directory — useful for project-specific servers. User scope (-s user) stores config globally — useful for personal tools available everywhere.

## Best practices

- Use project scope for project-specific servers and user scope for personal utility servers
- Always include -y in npx commands to prevent interactive prompts
- Commit .mcp.json to git for team sharing, but exclude files with hardcoded secrets
- Use claude mcp list regularly to audit your configured servers
- Test servers with MCP Inspector before adding them to Claude Code
- Use absolute paths for server files and directory arguments
- Pass API keys with -e flag rather than hardcoding in server source code
- Start with essential servers (filesystem, search) and add more as needed

## Frequently asked questions

### Does Claude Code support MCP resources and prompts?

Claude Code primarily uses MCP tools during its agentic workflow. Resource and prompt support depends on the Claude Code version. Tools are the most widely used capability in CLI-based MCP hosts.

### Can I use Claude Code MCP servers in a CI/CD pipeline?

Yes. Configure servers in .mcp.json and commit it to your repo. In CI, ensure the server commands are available (Node.js for npx servers, Docker for container-based servers) and environment variables are set.

### How do I update a server's configuration?

Remove the server with claude mcp remove server-name and re-add it with the updated configuration using claude mcp add. Alternatively, edit .mcp.json directly.

### Can Claude Code use MCP tools without asking for permission?

Claude Code has permission controls for MCP tools. By default, it may ask before executing certain tool calls. You can configure auto-approval for trusted servers in your Claude Code settings.

### Can RapidDev help build custom Claude Code MCP workflows?

Yes. RapidDev helps teams build custom MCP servers and configure Claude Code workflows for automated coding, code review, and DevOps tasks that leverage MCP tools for maximum effectiveness.

---

Source: https://www.rapidevelopers.com/mcp-tutorial/how-to-use-mcp-with-claude-code
© RapidDev — https://www.rapidevelopers.com/mcp-tutorial/how-to-use-mcp-with-claude-code