Troubleshooting

Most issues come down to one of three things: the tool hasn't restarted to pick up the new config, the config file has a syntax error, or the server's command isn't installed. The sections below cover the specific fixes for each common scenario.

My server doesn't appear in Claude Desktop after adding it

Claude Desktop reads its config at startup only. You must fully quit and reopen the app — closing the window is not enough. On macOS, right-click the Claude icon in the Dock and choose Quit, then relaunch.

If it still doesn't appear after restarting, open the config file at ~/Library/Application Support/Claude/claude_desktop_config.json and verify the server entry is present under mcpServers. If MCPBolt wrote the file correctly, the entry will be there. If the file is empty or missing the key, something interrupted the write — check the .bak file next to it.

Cursor shows an error loading MCP / the server doesn't appear

After writing, open Cursor's Settings, navigate to the MCP section, and click Refresh. A hard restart of Cursor is sometimes needed.

If Cursor reports a config parse error, the JSON file has a syntax issue. Open ~/.cursor/mcp.json (or .cursor/mcp.json for project scope) in a text editor and validate it — a missing comma or trailing comma before a closing brace is the usual culprit. MCPBolt won't produce invalid JSON, but manual edits can break it. Restore from the .bak file if needed.

VS Code doesn't show the new server / "Reload Window" required

VS Code requires a window reload to pick up MCP config changes. Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux), type Developer: Reload Window, and press Enter. The server should appear in the MCP panel after reload.

If it still doesn't appear, check that MCPBolt wrote to the correct scope. User-scope changes go to ~/Library/Application Support/Code/User/mcp.json; project-scope changes go to .vscode/mcp.json in your project root.

npx can't find mcpbolt / "command not found: mcpbolt"

If npx mcpbolt fails, Node.js is either not installed or is below version 18. Run node --version — if the command is not found, install Node from nodejs.org. If the version is below 18, upgrade via your version manager (nvm install 18, fnm install 18, etc.).

If you installed MCPBolt globally (npm install -g mcpbolt) and the mcpbolt command is still not found, the npm global bin directory is not on your PATH. Run npm bin -g to find the bin directory and add it to your ~/.zshrc or ~/.bashrc.

Permission denied when writing to ~/.claude.json or a config file

This usually means the config file is owned by root or has restrictive permissions. Check the permissions:

ls -la ~/.claude.json

If it's owned by root, you (or a previous tool run with sudo) created it with elevated privileges. Fix it:

sudo chown $USER ~/.claude.json
chmod 644 ~/.claude.json

Then run MCPBolt again.

Health status stuck on amber

Amber means the server is reachable but slow, or responded with a non-success status. Common causes:

• First run with npx -y — the package needs to download. Wait 30 seconds and click the health dot to re-check. It should turn green.
• Server takes longer than the timeout to start — Go to MCPBoltBar's Settings and increase the health check timeout.
• Remote server is rate-limiting the health check — Some servers return 429 on repeated HEAD requests. MCPBolt treats 429 as amber. This doesn't affect actual usage — your AI tool establishes its own session.

Server appears in MCPBolt but not in the AI tool

Confirm you selected the right scope when writing. Global scope writes to the user-level config file; project scope writes to a file inside your project directory. Open the target file and verify the entry is present. If it's not there, re-run MCPBolt and select the correct target.

Getting more help

If none of the above resolves your issue, open a GitHub Issue with as much detail as possible: the config you pasted, the target you selected, the exact error message, and your OS/Node version.

Open an issue on GitHub