MCP Servers in Claude Code: Transports & Safety
This guide explains how to set up Model Context Protocol (MCP) servers in Claude Code, covering the two main transport methods (stdio and HTTP/SSE) and the safety practices you should follow. You’ll learn how to add, configure, and manage MCP servers, and how to avoid common pitfalls. No prior MCP experience is needed, but you should be comfortable using a terminal and editing JSON files.
What You’ll Need
- Claude Code installed and authenticated (run
claudein your terminal to verify). - Node.js (v18 or later) and npm, if you plan to use npx-based servers.
- Python 3.8+ and pip, if you plan to use Python-based servers (e.g., via
uvxorpip). - Access to a terminal (macOS, Linux, or Windows with WSL).
- For remote HTTP servers: the server’s URL and any required API keys or tokens.
Step-by-Step
- Open Claude Code’s configuration file. The global configuration is at
~/.claude/settings.json(macOS/Linux) or%USERPROFILE%\.claude\settings.json(Windows). For project-specific settings, use.mcp.jsonin your project root. Create the file if it doesn’t exist. - Understand the two transport types. MCP servers can communicate via stdio (a local process, started automatically) or HTTP/SSE (a remote server, accessed via URL). Choose stdio for local, secure tools; choose HTTP for shared or cloud-hosted servers.
- Add a stdio server. In your settings file, add an
mcpServersobject. For example, to add the official filesystem server:{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"] } } }The
commandis the executable,argsare the arguments. The server will be launched automatically when Claude Code starts. - Add an HTTP/SSE server. For a remote server, use the
urlfield instead ofcommand:{ "mcpServers": { "remote": { "url": "https://mcp.example.com/sse", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }The
headersare optional but often needed for authentication. - Set environment variables (if needed). For stdio servers that require env vars (e.g., API keys), add an
envobject:"env": { "API_KEY": "your-key" }For security, consider using a .env file or Claude Code’s built-in secret management rather than hardcoding secrets.
- Save the file and restart Claude Code. Exit the current session and start
claudeagain. You should see the MCP servers listed in the startup output or by running/mcpin the CLI. - Verify the server is working. Ask Claude Code to use a tool from the server, e.g., “List files in the allowed directory” for the filesystem server. If the tool fails, check the server logs (see Troubleshooting).
- Scope access carefully. For stdio servers, restrict file paths and network access to only what the server needs. For HTTP servers, use the principle of least privilege: only grant permissions that are essential.
- Review and update regularly. MCP servers can introduce vulnerabilities. Periodically review the list of enabled servers, remove unused ones, and update server packages to their latest versions.
Common Mistakes
- Using the wrong transport type. Some servers only support stdio; others only HTTP. Check the server’s documentation before configuring.
- Misplacing the configuration file. Putting MCP settings in the wrong file (e.g.,
settings.jsonvs.mcp.json) can cause them to be ignored. - Hardcoding secrets. Storing API keys directly in the JSON file exposes them to anyone with file access. Use environment variables or a secrets manager.
- Overly broad file access. Giving a filesystem server access to your entire home directory can lead to accidental data loss or exposure. Always restrict to a specific subdirectory.
- Forgetting to restart. Changes to the config file only take effect after restarting Claude Code.
Tips
- Use
claude mcp addfor quick setup. Instead of editing JSON manually, you can runclaude mcp add <name> -- <command> <args>for stdio servers, orclaude mcp add <name> --transport http <url>for HTTP servers. - Test with a simple server first. Start with the official filesystem or fetch server to confirm the setup works before adding complex tools.
- Use project-specific config for shared projects. A
.mcp.jsonin your project root can be committed to version control, but avoid committing secrets—use environment variables instead. - Monitor server output. For stdio servers, you can see logs in Claude Code’s debug mode (
--debugflag) to diagnose issues. - Keep servers updated. MCP servers are evolving; check for updates regularly to get bug fixes and security patches.
Troubleshooting
- Server not listed after restart. Check the JSON syntax (commas, braces). Run
claude mcp listto see what Claude Code recognizes. If it’s not there, the file path or structure is wrong. - Server fails to start. For stdio servers, try running the command manually in your terminal. If it errors, the issue is with the command or dependencies. For HTTP servers, check the URL is reachable (
curlit) and that the server supports the SSE or streamable HTTP protocol. - Tool calls time out. This often happens with slow HTTP servers. Increase the timeout in your client settings if available, or check the server’s network latency.
- Authentication errors. For HTTP servers, verify your headers are correctly formatted and that the token is valid. For stdio servers that need API keys, ensure the env vars are set correctly.
- Permission denied when accessing files. Ensure the path you gave the server is correct and that the server process has read/write permissions to that directory.
Frequently Asked Questions
Can I use multiple MCP servers at once?
Yes, you can define as many servers as you need in the mcpServers object. Each server’s tools will be available to Claude Code, but be mindful of tool name conflicts—later servers may override earlier ones.
What’s the difference between stdio and HTTP/SSE?
Stdio runs the server as a local child process, which is faster and more secure for local tools. HTTP/SSE connects to a remote server over the network, which is useful for shared or cloud-hosted services, but introduces latency and requires network security considerations.
How do I remove an MCP server?
Simply delete its entry from the mcpServers object in your config file, or run claude mcp remove <name> if you added it via CLI. Restart Claude Code to apply the change.
Are MCP servers safe to use?
MCP servers are as safe as the code you run. Only install servers from trusted sources, review what tools they expose, and restrict their permissions (e.g., file access) to the minimum needed. Never grant a server access to sensitive data unless necessary.
Can I use MCP servers with Claude Code on Windows?
Yes, but you may need to use WSL for some stdio commands (like npx). The configuration file path is slightly different, but the JSON structure is the same.
What happens if a server crashes?
Claude Code will attempt to restart stdio servers automatically. For HTTP servers, the connection is re-established on the next request. If the crash persists, check the server logs and the server’s health endpoint.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.