Setting Up MCP Servers with Claude Code

Claude Code is Anthropic's official CLI for Claude, and it supports MCP servers natively. Adding MCP servers to Claude Code gives the assistant direct access to your filesystem, GitHub repositories, databases, and any other system you expose through a server.

This guide covers everything you need to get MCP servers running with Claude Code: the configuration file format, how to add and manage servers, passing credentials safely, and verifying that connections work.

How Claude Code Loads MCP Servers

When Claude Code starts, it reads MCP server configuration from one or more JSON files and launches each configured server as a child process. Communication happens over stdio — Claude Code writes JSON-RPC requests to the server's stdin and reads responses from its stdout.

Claude Code looks for configuration in two locations:

1. Project-level: .claude/mcp.json in your current working directory (or project root)
2. User-level: ~/.claude/mcp.json in your home directory

Project-level config takes precedence and is useful for servers specific to a single codebase. User-level config applies to all projects and is the right place for general-purpose servers like filesystem or GitHub.

The Configuration File Format

Both config files use the same format:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/expose"],
      "env": {
        "ENV_VAR_NAME": "value"
      }
    }
  }
}

Each key under mcpServers is an arbitrary name you give the server — Claude Code uses it in logs and status output. The value is an object with:

• command — the executable to run (e.g., node, npx, uvx, python)
• args — array of arguments passed to the command
• env — optional object of environment variables set for the server process

Adding Servers with the CLI

Claude Code provides a mcp subcommand for managing servers without editing JSON directly.

Add a server

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

This appends the server to your user-level config file. Claude Code infers the config format from the command and arguments you provide.

List configured servers

claude mcp list

Output shows each server name, its command, and whether it started successfully in the last session.

Remove a server

claude mcp remove filesystem-server

View server details

claude mcp get filesystem-server

Shows the full configuration for a single server, including any environment variables (with values masked).

Setting Up the Filesystem Server

The filesystem server is the most commonly added server and a good starting point. It gives Claude access to read and write files in specified directories.

Install and add it with:

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

Or edit your ~/.claude/mcp.json directly:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    }
  }
}

You can pass multiple directory paths as additional arguments:

{
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "/Users/yourname/projects",
    "/Users/yourname/Documents/notes"
  ]
}

The server enforces that all operations stay within these directories. It cannot access parent directories or other paths even if Claude requests them.

Setting Up the GitHub Server

The GitHub server requires a personal access token. Store it in the server's env block rather than hardcoding it in args or setting it as a shell environment variable:

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

Token permissions

Create a fine-grained personal access token at github.com/settings/personal-access-tokens with:

• Repository permissions: Contents (read), Issues (read/write), Pull requests (read/write)
• Account permissions: None required for most workflows

Avoid using a classic token with broad scopes. Fine-grained tokens limit what the server can do if something goes wrong.

Project-Specific Configuration

For project-specific servers — say, a Postgres server pointing at your project's database — create a .claude/mcp.json in the project root:

{
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://localhost:5432/myproject_dev"
      }
    }
  }
}

Add .claude/mcp.json to your .gitignore if it contains credentials. Alternatively, reference environment variables using shell syntax — Claude Code expands variables from your current environment when it reads the config:

{
  "env": {
    "POSTGRES_URL": "${DATABASE_URL}"
  }
}

This lets teammates each have their own credentials without the config file containing sensitive values.

Verifying Server Connections

After adding a server, start a Claude Code session and ask Claude directly:

What MCP tools do you have available?

Claude will list the tools from all connected servers. If a server failed to start, it will not appear in the list.

For a more targeted check with the filesystem server:

List the files in my projects directory.

For the GitHub server:

List my open pull requests on GitHub.

If Claude cannot find any tools, check the server logs. Claude Code writes MCP server stderr to log files at:

~/.claude/logs/mcp-server-<server-name>.log

Using MCP Tools in Practice

Once servers are connected, Claude uses their tools automatically based on your requests. You do not need to prefix requests with special syntax.

Example: Code review with filesystem access

Read the changes in src/auth/ and identify any potential security issues.

Claude reads the relevant files via the filesystem server and analyzes them in context.

Example: GitHub workflow

Find all issues in this repo labeled "bug" and summarize the top three by priority.

Claude queries the GitHub server's list_issues tool, reads the results, and synthesizes a summary.

Example: Combined workflow

Read the schema from the database and generate TypeScript types that match our existing conventions (check src/types/ for examples).

Claude reads the database schema via the Postgres server, reads the existing type files via the filesystem server, and generates new type definitions that match your style.

Managing Multiple Environments

If you work across staging and production environments, use separate server entries with distinct names:

{
  "mcpServers": {
    "db-staging": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "POSTGRES_URL": "${STAGING_DATABASE_URL}" }
    },
    "db-prod": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "POSTGRES_URL": "${PROD_DATABASE_URL}" }
    }
  }
}

You can then ask Claude explicitly which database to query, or let it infer from context.

Performance Considerations

Each MCP server is a separate process. Starting ten servers adds startup time to Claude Code sessions. A few guidelines:

• Add servers to user-level config only if you use them regularly across many projects
• Use project-level config for servers that are only relevant to one codebase
• Servers that are slow to start (e.g., those that download packages on first run) can be pre-warmed with claude mcp list before starting a session

What's Next

With filesystem and GitHub servers running, you have the most commonly needed capabilities covered. From there:

• Add sequential-thinking-server for complex planning tasks
• Add a database server (Postgres, SQLite, MySQL) if you work with databases regularly
• Consider building a custom server if you have internal APIs that none of the existing servers cover

The configuration format is the same for every server, so adding new ones takes less than a minute once you know the pattern.