ThisCalculator

Everyday

MCP Servers in Claude Code: Transports & Safety

Updated · Standard formula, shown below

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 claude in 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 uvx or pip).
  • 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

  1. 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.json in your project root. Create the file if it doesn’t exist.
  2. 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.
  3. Add a stdio server. In your settings file, add an mcpServers object. For example, to add the official filesystem server:
    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
        }
      }
    }

    The command is the executable, args are the arguments. The server will be launched automatically when Claude Code starts.

  4. Add an HTTP/SSE server. For a remote server, use the url field instead of command:
    {
      "mcpServers": {
        "remote": {
          "url": "https://mcp.example.com/sse",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
          }
        }
      }
    }

    The headers are optional but often needed for authentication.

  5. Set environment variables (if needed). For stdio servers that require env vars (e.g., API keys), add an env object:
    "env": {
      "API_KEY": "your-key"
    }

    For security, consider using a .env file or Claude Code’s built-in secret management rather than hardcoding secrets.

  6. Save the file and restart Claude Code. Exit the current session and start claude again. You should see the MCP servers listed in the startup output or by running /mcp in the CLI.
  7. 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).
  8. 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.
  9. 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.json vs .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 add for quick setup. Instead of editing JSON manually, you can run claude mcp add <name> -- <command> <args> for stdio servers, or claude 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.json in 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 (--debug flag) 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 list to 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 (curl it) 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.