The two ways to add an MCP server in Claude Code
Claude Code gives you two paths to connect an MCP server. The fastest is the CLI: `claude mcp add <name> -- npx -y <package>`. This registers the server and writes the config for you.
The second is editing the config file directly, which you'll want when you need fine control over environment variables, arguments, or a remote HTTP endpoint. Both end up in the same place — the CLI is just a convenience wrapper.
Whichever you use, the mental model is the same: you're telling Claude Code the command to launch the server (for local stdio servers) or the URL to reach it (for remote servers).
The config file: shape and location
The core of MCP configuration is a JSON block under an `mcpServers` key. Each server gets a name, a `command` (e.g. `npx`), and an `args` array (the package and any flags).
A minimal local server looks like this: `{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"] } } }`. The last arg here is the directory the server is allowed to touch.
After editing the file, restart Claude Code so it re-reads the config and launches the server as a child process.
Passing secrets: environment variables, not plaintext
Most useful servers need a credential — a GitHub token, a database URL, an API key. Pass these through an `env` object in the server's config block, not hardcoded into args where they'd leak into logs and shell history.
Example: a GitHub server takes `"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }`. Scope the token to the minimum permissions the task needs — a read-only token for read-only work.
For servers you share across a team, keep the token out of committed config and inject it from your shell environment instead.
Verifying the server actually connected
After restarting, the quickest check is to ask Claude directly: "what MCP tools do you have?" If the server connected, its tools show up in the list.
If they don't, the server failed to start. The two most common causes are a wrong package name (typo in `args`) and a missing runtime (the server needs Node or Python you don't have).
Run the server's launch command manually in a terminal — e.g. `npx -y <package>` — to see the real error message, which Claude Code otherwise swallows.
The errors people hit most
"Server disconnected" right after launch: usually a missing required environment variable. Check the server's README for which env vars it needs.
Tools appear but every call fails: almost always a credential/permission problem — the token is expired, or scoped too narrowly for the action.
Server works in one client but not Claude Code: different clients read config from different files. Make sure you edited Claude Code's config, not Claude Desktop's.
Once it's connected and a test call returns real data, you're done — the server is now part of Claude's context and you can use it in plain language.