Use MCP With Claude Code CLI | Tutorial

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.

Prerequisites

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

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.

typescript

1# Add the filesystem MCP server
2claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects
3
4# Add a custom TypeScript server
5claude mcp add my-server -- npx -y tsx /path/to/server/src/index.ts
6
7# Add a Python server
8claude 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.

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.

typescript

1# Add Brave Search server with API key
2claude mcp add brave-search -e BRAVE_API_KEY=your-key -- npx -y @modelcontextprotocol/server-brave-search
3
4# Add GitHub server (Docker) with token
5claude 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
6
7# Add a server with multiple env vars
8claude 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.

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.

typescript

1# Project scope (default) — stored in .mcp.json, team-shareable
2claude mcp add project-db -- npx -y tsx /path/to/project/db-server.ts
3
4# User scope — available in all projects, personal
5claude mcp add -s user filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you
6claude 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.

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.

typescript

1# List all configured MCP servers
2claude mcp list
3
4# Remove a server
5claude mcp remove my-server
6
7# Remove a user-scope server
8claude mcp remove -s user filesystem

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

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.

typescript

1// .mcp.json (in project root)
2{
3  "mcpServers": {
4    "filesystem": {
5      "command": "npx",
6      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"],
7      "env": {}
8    },
9    "github": {
10      "command": "docker",
11      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
12      "env": {
13        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
14      }
15    }
16  }
17}

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

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.

typescript

1# Start a Claude Code session
2claude
3
4# Or start with a specific task
5claude "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 working example

.mcp.json

1{
2  "mcpServers": {
3    "filesystem": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "@modelcontextprotocol/server-filesystem",
8        "/Users/you/projects"
9      ],
10      "env": {}
11    },
12    "github": {
13      "command": "docker",
14      "args": [
15        "run", "-i", "--rm",
16        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
17        "ghcr.io/github/github-mcp-server"
18      ],
19      "env": {
20        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
21      }
22    },
23    "brave-search": {
24      "command": "npx",
25      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
26      "env": {
27        "BRAVE_API_KEY": "your-brave-api-key"
28      }
29    },
30    "memory": {
31      "command": "npx",
32      "args": ["-y", "@modelcontextprotocol/server-memory"],
33      "env": {}
34    },
35    "postgres": {
36      "command": "npx",
37      "args": ["-y", "@modelcontextprotocol/server-postgres"],
38      "env": {
39        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
40      }
41    }
42  }
43}

Common mistakes when using MCP with Claude Code

Why it's a problem: Forgetting the -- separator before the server command

How to avoid: 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.

Why it's a problem: Adding secrets to project-scope .mcp.json and committing to git

How to avoid: 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.

Why it's a problem: Not using -y flag in npx commands

How to avoid: Claude Code spawns server processes non-interactively. Without -y, npx prompts for installation confirmation and the server hangs. Always include -y in npx commands.

Why it's a problem: Confusing project and user scope

How to avoid: 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

Still stuck?

Copy one of these prompts to get a personalized, step-by-step explanation.

ChatGPT Prompt

Show me how to use MCP servers with Claude Code CLI. I want to add the filesystem server, GitHub server (Docker), and Brave Search. Show the claude mcp add commands with environment variables, and explain the difference between project and user scope.

MCP Prompt

Help me set up MCP servers in Claude Code. I want to add filesystem and GitHub servers. Show the CLI commands and the resulting .mcp.json file. Also explain when to use project scope vs user scope.

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.

Talk to an Expert

Our team has built 600+ apps. Get personalized help with your project.

Book a free consultation

How to use MCP with Claude Code

What you'll learn

What you'll learn

Use MCP Servers with Claude Code CLI

Prerequisites

Step-by-step guide

Add an MCP server using the CLI

Add an MCP server using the CLI

Add servers with environment variables

Add servers with environment variables

Choose between project scope and user scope

Choose between project scope and user scope

List and manage configured servers

List and manage configured servers

Edit .mcp.json directly for advanced configuration

Edit .mcp.json directly for advanced configuration

Use MCP tools during a Claude Code session

Use MCP tools during a Claude Code session

Complete working example

Common mistakes when using MCP with Claude Code

Best practices

Still stuck?

Frequently asked questions

Talk to an Expert

Need help with your project?

We put the rapid in RapidDev

How to use MCP with Claude Code

What you'll learn

Use MCP Servers with Claude Code CLI

Prerequisites

Step-by-step guide

Add an MCP server using the CLI

Add an MCP server using the CLI

Add servers with environment variables

Add servers with environment variables

Choose between project scope and user scope

Choose between project scope and user scope

List and manage configured servers

List and manage configured servers

Edit .mcp.json directly for advanced configuration

Edit .mcp.json directly for advanced configuration

Use MCP tools during a Claude Code session

Use MCP tools during a Claude Code session

Complete working example

Common mistakes when using MCP with Claude Code

Best practices

Still stuck?

Related tutorials

How to Connect MCP to Claude Desktop

How to Connect MCP to Cursor

How to Use Multiple MCP Servers Together

Best MCP Servers for Developers

Frequently asked questions

Talk to an Expert

Need help with your project?

We put the rapid in RapidDev