$ man how-to/managing-mcp-servers

CODE

MCP server configurations live in JSON files. The location depends on your tool: Cursor (project-level): .cursor/mcp.json in your project root Cursor (global): ~/.cursor/mcp.json in your home directory Claude Code: ~/.claude/mcp.json or project-level .claude/mcp.json Project-level configs override global configs. Use global configs for servers you need in every project (GitHub, Slack). Use project-level configs for servers specific to one project. Both files share the same format: a JSON object with a "mcpServers" key containing one block per server. Each block has a "command" (how to start the server), "args" (arguments to the command), and "env" (environment variables, usually API keys).

PATTERN

The /addmcp skill automates this, but understanding the manual process helps when things break. 1. Find the npm package for the MCP server. Most are published on npm with names like @company/mcp-server or mcp-server-toolname. 2. Get the API key from the tool's settings or dashboard. 3. Add a new block to your mcp.json with the server name, command (usually "npx"), args (the package name with "-y" flag), and env (your API key). 4. Restart your editor so it picks up the new config. 5. Test by asking Claude to use the tool. "List my Slack channels" or "Show my HeyReach campaigns." If the test fails, the issue is almost always the API key (wrong or expired) or the package name (typo or wrong version).

PRO TIP

When an MCP server stops working, check these in order: 1. API key: Has it expired? Did you rotate it? Check the tool's dashboard. 2. Config syntax: Is the JSON valid? A missing comma or bracket breaks the entire config file, not just one server. 3. Package availability: Can you run the npx command manually in the terminal? If it fails there, it fails in the IDE too. 4. Network: Is the external service up? Check the tool's status page. 5. Rate limits: Did you hit the API rate limit? Some services throttle after too many requests. Add delays between calls or reduce batch sizes. The most common issue by far is expired API keys. If a server worked yesterday and fails today, check the key first. Save yourself 20 minutes of debugging by starting with the obvious.

ANTI-PATTERN

Do not add MCP servers you do not actively use. Each server adds startup time. Some servers run background processes that consume memory. If you are not using the Figma MCP daily, remove it. You can always add it back in 30 seconds. Do not hardcode API keys in files that get committed. The mcp.json file should be in your .gitignore. If you share a project with collaborators, create an mcp.json.example with placeholder values and add the real mcp.json to .gitignore. Do not install every MCP server from a "top 50 MCP servers" list. Install the ones that remove friction from workflows you already do. The value of an MCP server is measured by how many manual steps it eliminates from your daily process. Zero manual steps eliminated means zero value, regardless of how cool the tool is.