Claude Code manages MCP servers from the command line rather than a hand-edited JSON file. The claude mcp commands add, list and remove servers, with three scopes to control who sees them. Here is the setup.
Add a stdio server
The general form is claude mcp add <name> -- <command> <args>. Everything after -- is the server command:
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects
Pass environment variables with -e:
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
Add a remote (HTTP) server
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer ghp_xxx"}}'
Scopes: local, project, user
Use --scope (or -s) to control visibility:
- local (default) — just you, just this project.
- project — shared with the team via a
.mcp.jsonfile committed to the repo. Great for sharing config across a team. - user — available to you across all projects.
claude mcp add postgres --scope project -- npx -y @bytebase/dbhub --transport stdio --dsn "postgres://..."
Manage servers
claude mcp list— see configured servers and their status.claude mcp get <name>— details for one server.claude mcp remove <name>— delete it.
Inside a session, type /mcp to see live connection status and authenticate remote servers.
Common problems
- Server shows "failed" — run the bare command in a terminal to see the crash. See MCP "connection closed" error.
- Forgot the
--— everything after--is the command; without it, flags are parsed by Claude Code, not the server. - Token in shell history — prefer
-e VARreferencing an exported env var over inlining secrets. See MCP security best practices.
Going further
Popular servers to add: GitHub, Postgres, Playwright. Or start from a curated loadout.