ThisCalculator

Everyday

Add an MCP Server to Claude Code with claude mcp add

Updated · Standard formula, shown below

This guide shows you how to connect an MCP (Model Context Protocol) server to Claude Code using the built-in claude mcp add command. This lets Claude Code access external tools, data sources, or custom functions during your coding sessions. You’ll need Claude Code installed and authenticated, and the MCP server you want to add must be running or have a start command available.

What You’ll Need

  • Claude Code installed and logged in (run claude --version to check).
  • The MCP server’s connection details: either a command (like npx or python) or a URL (for remote servers).
  • Node.js or Python installed if your MCP server runs via those runtimes.
  • Basic terminal access in the project directory where you want the server available.

Step-by-Step

  1. Open your terminal in the project folder where you’ll use Claude Code. The MCP server you add will be scoped to this project unless you choose a different scope.
  2. Verify Claude Code is ready by running claude --version. If it’s not installed, follow the official installation instructions for your OS.
  3. Decide on the scope for the MCP server. You can add it locally (only this project), user-wide (all your projects), or project-wide (shared with your team via a config file). The command syntax supports --scope local, --scope user, or --scope project. The default is local.
  4. Add a server that runs via a command. For example, to add a server that starts with npx, run:
    claude mcp add my-server -- npx my-mcp-server
    Replace my-server with a name you’ll recognize, and npx my-mcp-server with the actual start command.
  5. Add a server that runs via a Python command. If your server is a Python script, use:
    claude mcp add my-python-server -- python /path/to/server.py
    Make sure the path is absolute or relative to the project root.
  6. Add a remote server via URL. For an HTTP-based MCP server, use:
    claude mcp add --transport http my-remote-server https://example.com/mcp
    This works for servers that expose an MCP endpoint over HTTP.
  7. Add a server with environment variables. If the server needs API keys or tokens, pass them inline:
    claude mcp add my-server --env KEY=value -- npx my-mcp-server
    You can repeat --env for multiple variables.
  8. Verify the server was added by running claude mcp list. You should see your server name, transport type, and status.
  9. Test the connection by starting a Claude Code session (claude) and asking Claude to use a tool from that server. For example, if the server provides a database query tool, ask Claude to run a simple query.
  10. Remove or update if needed. Use claude mcp remove my-server to delete it, or re-run the add command with the same name to overwrite the configuration.

Common Mistakes

  • Forgetting the -- separator before the command. Without it, Claude Code may interpret the command as part of its own flags.
  • Using a relative path for a Python script when the server runs from a different working directory. Use an absolute path or adjust the command to cd first.
  • Adding a server that requires environment variables without providing them. The server may start but fail to authenticate.
  • Choosing the wrong scope. Adding with --scope user makes it available everywhere, which might expose sensitive tools to other projects.
  • Not checking if the server is already running for remote URLs. If the URL is unreachable, Claude Code will show an error.

Tips

  • Use descriptive names for your MCP servers so you can easily identify them in claude mcp list.
  • For development, start with --scope local to test before making it user-wide.
  • If your server has many environment variables, consider putting them in a .env file and using a tool like dotenv in your server’s start command, but remember Claude Code won’t load that file automatically unless you pass it.
  • Check the server’s documentation for the exact start command and any required flags.
  • Keep your MCP server configuration in version control if you use --scope project, so your team gets the same setup.

Troubleshooting

Server not showing in claude mcp list: Re-run the add command and check for typos. Ensure you used the correct scope flag. If you added it with --scope local, you must be in the same project directory to see it.

Connection error when using the server: First, test the server manually by running the start command in your terminal. If it fails, the issue is with the server itself. If it starts, check that the command in Claude Code matches exactly, including any flags or paths.

Permission denied when running the server: Make sure the executable (like npx or python) is in your PATH. You can test by running which npx or which python.

Environment variables not picked up: Verify you passed them with --env correctly. Also check that the variable names match what the server expects. Some servers read from a specific config file, not from environment variables.

Server added but not available in Claude Code session: Restart Claude Code completely. MCP servers are loaded at session start. If you added the server while a session was open, it won’t appear until you restart.

HTTP server returns 404 or 401: Check the URL is correct and the server is running. For authentication, you may need to pass an Authorization header, which Claude Code might not support directly yet—check the server’s docs for alternative auth methods.

Frequently Asked Questions

Q: Can I add multiple MCP servers?
A: Yes, you can add as many as you need. Each must have a unique name. Use claude mcp add for each one, and they’ll all appear in claude mcp list.

Q: What’s the difference between local, user, and project scope?
A: Local scope makes the server available only in the current project directory. User scope makes it available in all your projects. Project scope stores the config in a shared file (like .mcp.json) that can be committed to version control for your team.

Q: Can I use an MCP server that requires OAuth or a login?
A: Some servers support OAuth via the MCP protocol. Claude Code may handle the OAuth flow automatically if the server supports it. For others, you might need to obtain an access token and pass it as an environment variable.

Q: How do I update an existing MCP server’s configuration?
A: Simply re-run the claude mcp add command with the same name and new details. It will overwrite the previous configuration.

Q: Can I remove an MCP server?
A: Yes, use claude mcp remove <server-name>. This removes it from the scope where it was added.

Q: What if my MCP server is a local script that needs to stay running?
A: The server should be a long-running process. If it’s a script that exits, it won’t work. Ensure your server stays alive and listens for MCP messages. Many MCP SDKs handle this automatically.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.