Setup guide

How to add an MCP server to Claude Code

Claude Code adds MCP servers from the command line with `claude mcp add`, and also reads a project-level `.mcp.json` you can commit so the whole team gets the same servers.

Where the config lives

  • Project (shared with your team): .mcp.json in the repository root
  • User (all projects): ~/.claude.json, written by `claude mcp add --scope user`

Servers go under the mcpServers key (or are added with the CLI).

What Claude Code can run

  • Local servers (stdio)
  • Remote servers (HTTP)
  • Remote servers (SSE)

504 of the 508 servers in the catalog run natively in Claude Code.

Step by step

  1. Run `claude mcp add <name> -- <command> <args>` for a local server, or `claude mcp add --transport http <name> <url>` for a remote one.
  2. Pass credentials with `-e KEY=value` (local) or `--header "Authorization: Bearer …"` (remote).
  3. Check it connected with `claude mcp list`, or `/mcp` inside a session.

Reloading: New servers are picked up the next time you start `claude`. Use `/mcp` in a session to reconnect one.

Example: the Filesystem server in Claude Code

The official reference server for file access. Replace the directory with the folder you want the assistant to see.

Add the server

bash
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

Verify it's connected

bash
claude mcp list

Troubleshooting

A remote server is added but Claude tries to execute the URL
`--transport http` (or `sse`) is required for remote servers; without it the URL is treated as a local command.
`SyntaxError` or `Unsupported engine` when the server starts
Most MCP servers need Node.js 18 or newer (`node -v`). If you use nvm, the client may not see your shell's Node: point `command` at the absolute path of `npx`.
`uvx: command not found` for Python servers
Install uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`, or `winget install astral-sh.uv` on Windows), then restart the client so it picks up the new PATH.
The server starts but every tool call fails with 401 or 403
Its API key is missing or wrong. Put it in the server's `env` block (or the header for remote servers) — never in a file you commit.

Official documentation: Claude Code MCP docs

Setting up several servers at once?

Tick them in the catalog and the setup builder merges them into one Claude Code config.

Open the setup builder for Claude Code

Best MCP servers for Claude Code

The highest health scores among servers that run natively in Claude Code.

See every server that runs in Claude Code →