MCP Troubleshooting
Got an error while connecting RubberDuck to your AI tool? Pick your tool, then the problem you're seeing. Token and connection errors apply to every tool.
Claude Code
Problem: No RubberDuck servers, or no RubberDuck tools
Servers added with “claude mcp add” belong to the project folder you added them in. Start Claude Code in a different folder and they aren't there.
Solution
- 1Open a terminal in the project folder where you ran the setup and start Claude Code with
claude. - 2Check which servers Claude Code knows about:
claude mcp list - 3No RubberDuck servers listed? You're in a different folder from the setup, or the setup never finished. Run the setup again in this folder: copy the prompt from the Claude Code tab of the Setup Guide and paste it into Claude Code, or run the commands under “Setup stops at a permission prompt” below.
- 4Listed but marked as failed? Inside Claude Code, type
/mcpto see each server's error. A 401 or “unauthorized” error means your token: see the Token & connection tab. - 5Exit Claude Code and start it again in the same folder, so it loads the servers.
Confirm it worked: Both RubberDuck servers show as connected in /mcp, and asking for something small and read-only calls a RubberDuck tool.
Problem: Setup stops at a permission prompt
Symptom: Claude refuses to write a configuration file that contains your token, or setup stops before the servers are added.
Solution
- 1Copy a fresh prompt from the Claude Code tab of the Setup Guide instead of reusing an old saved one. It has Claude Code run “claude mcp add” rather than write a file.
- 2Still blocked? Run the commands yourself, in your project folder, in your terminal (not in the Claude chat). Replace YOUR_TOKEN with your token from Change Token.
claude mcp add --transport http rubberduck-codebase-intelligence https://codebase.rubberduck.com/mcp --header "Authorization: Bearer YOUR_TOKEN" claude mcp add --transport http rubberduck-semantic-intelligence https://semantic.rubberduck.com/mcp --header "Authorization: Bearer YOUR_TOKEN" - 3If a command says the server already exists, remove the old entries, then run the add commands again:
claude mcp remove --scope local rubberduck-codebase-intelligence claude mcp remove --scope local rubberduck-semantic-intelligence - 4If Claude asks for a permission, approve only the setup step. Don't turn off its safeguards to force it through.
- 5Exit Claude Code and start it again in the same folder.
Confirm it worked: “claude mcp list” shows both RubberDuck servers as connected.
Problem: Set up with .mcp.json, but the servers fail or show 401
The .mcp.json from the manual setup reads your token from the RUBBERDUCK_TOKEN environment variable, so the file never holds it. Claude Code must start with that variable set.
Solution
- 1Start Claude Code in the project folder. The first time, it asks you to approve the servers in .mcp.json: approve both RubberDuck servers.
- 2Save the token for every new terminal. Replace YOUR_TOKEN with your token from Change Token, and run the line for your system:
# macOS echo 'export RUBBERDUCK_TOKEN=YOUR_TOKEN' >> ~/.zshrc # Linux echo 'export RUBBERDUCK_TOKEN=YOUR_TOKEN' >> ~/.bashrc - 3Windows: run this in PowerShell instead.
[Environment]::SetEnvironmentVariable( "RUBBERDUCK_TOKEN", "YOUR_TOKEN", "User" ) - 4Fully quit Claude Code, open a new terminal, and check the token is there without printing it:
# macOS / Linux [ -n "$RUBBERDUCK_TOKEN" ] && echo set || echo missing # Windows PowerShell if ($env:RUBBERDUCK_TOKEN) { "set" } else { "missing" } - 5Start Claude Code from that terminal in the project folder, and type /mcp.
Confirm it worked: /mcp shows both RubberDuck servers as connected, also from a brand-new terminal.
Using Claude Desktop? RubberDuck's setup covers Claude Code in a terminal. Servers added with “claude mcp add” don't appear in Claude Desktop, so don't paste these commands into its config file. Use Claude Code in a terminal, or ask support.
Still stuck?
Email support with these details, so we can help without asking for them first:
- Your tool and how you use it (CLI, desktop app or editor extension), its version, and your operating system.
- How you set it up (one click, prompt or manual) and which RubberDuck server failed.
- The exact error, and the time it happened with your timezone.
- What you already tried, including whether a reload or full restart changed anything.
- A screenshot if it helps, with your token and any authorization headers removed.
Never include your token in a support message.