Installing and configuring an MCP

The MCP configuration file

MCPs are configured in a JSON file that tells Claude Code which MCP servers to launch and how to connect them. There are two levels of configuration: global for your personal tools, and per-project for each repository's tech stack.

.mcp.json file structure

{
  "mcpServers": {
    "mcp-name": {
      "command": "npx",
      "args": ["-y", "@package/mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Each entry in mcpServers defines an MCP with:

• command: the command to launch the MCP server (npx, uvx, docker, or a path to a binary)
• args: the arguments passed to the command (the npm package, configuration options)
• env (optional): required environment variables (tokens, API keys)

Installing an MCP: three methods

# General syntax
claude mcp add <name> -- <command> <args...>

# Example: add Context7
claude mcp add context7 -- npx -y @upstash/context7-mcp

# Example: add GitHub with a token
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Example: add an MCP with environment variables
claude mcp add slack -e SLACK_BOT_TOKEN=xoxb-your-token -- npx -y @modelcontextprotocol/server-slack

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    }
  }
}

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URL",
        "mcp/postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname"
      }
    }
  }
}

Configuration in Claude Code

Check installed MCPs

After adding an MCP, restart Claude Code and verify it's connected.

# List all configured MCPs
claude mcp list

# Expected output:
# context7: connected
#   Tools: query-docs, resolve-library-id
# github: connected
#   Tools: list_issues, create_pull_request, search_code, ...

# Remove an MCP
claude mcp remove <name>

# View details of an MCP
claude mcp get <name>

Configuration scope

# Add an MCP at the project level (default)
claude mcp add context7 -- npx -y @upstash/context7-mcp

# Add an MCP at the global level (all projects)
claude mcp add context7 --scope global -- npx -y @upstash/context7-mcp

# Add an MCP at the user level (for this user)
claude mcp add context7 --scope user -- npx -y @upstash/context7-mcp

Debug and troubleshooting

The MCP won't connect

# Check that npx is installed
which npx

# Check that the MCP package exists
npx -y @upstash/context7-mcp --help

# If you're using uvx (Python)
which uvx

# View MCP connection logs
claude mcp logs

# View logs for a specific MCP
claude mcp logs context7

# Validate your .mcp.json file
cat .mcp.json | python3 -m json.tool

# Or with Node.js
node -e "console.log(JSON.parse(require('fs').readFileSync('.mcp.json','utf8')))"

# Launch the MCP server directly
npx -y @upstash/context7-mcp

# If the server starts and waits for stdin input, it's working
# Ctrl+C to quit

Common errors and solutions

Full example: configuring three MCPs

Here's a realistic configuration example with three MCPs for a web development project.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

With this configuration, you can ask Claude Code:

"Look up the Next.js 14 docs, create a 404 error page following best practices, test it in the browser, and create a pull request."

Claude Code will automatically chain Context7 (documentation), file editing (page creation), Playwright (visual testing), and GitHub (pull request).

Next steps

Is your first MCP configured? Now discover the best MCPs by category.

• Understanding MCPs: How the MCP protocol works, explained
• Top productivity MCPs: Gmail, Slack, Calendar, Figma, Lighthouse
• Top development MCPs: Context7, GitHub, Sentry, databases
• Top design & UI MCPs: Playwright, Chrome DevTools, 21st.dev Magic