Intermediate9 min
Adding and Configuring MCP Servers
The complete reference for adding, configuring, and verifying MCP servers in Claude Code — covering the CLI commands, JSON config format, stdio vs HTTP transport, environment variable injection, and in-session management.
Quick Reference
- →claude mcp add <name> -- <command> for stdio servers
- →claude mcp add <name> --transport http --url <url> for remote servers
- →Project config: .mcp.json in repo root (committed and shared)
- →Global config: ~/.claude.json (personal, never committed)
- →Use ${ENV_VAR} for every secret — never hardcode in config
- →/mcp shows server status, tools, and lets you reconnect mid-session
- →Environment variables pass secrets to MCP server processes via the env block
Where Config Lives
MCP servers can be configured at two levels: project and global. Understanding the difference determines what gets committed to git and what stays personal.
| Level | File | Scope | Commit to git? |
|---|---|---|---|
| Project | .mcp.json in repo root | Everyone who clones the repo | Yes |
| Global | ~/.claude.json | Your machine only | Never |
For servers the whole team should use — GitHub, Linear, your internal API — put them in .mcp.json. For personal experimentation or secrets you cannot share — a personal database, a paid API key only you have — use global config.