For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at /guide/mcp/troubleshooting.md.
Troubleshooting
Tools not appearing, 401s, Node.js problems and rate limits — the things that actually go wrong.
Work top-down: prove the server accepts your key first, then look at the client.
#Step 1 — does the server accept your key?
Run this on the same machine as the client:
curl -sS -X POST https://v4-api.orangescrum.com/mcp/partner \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: YOUR_KEY' \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
| Result | Meaning | Next |
|---|---|---|
| A list of 15 tools | Server and key are fine | The problem is client-side — step 2 |
401 | Key wrong, missing, expired or revoked | Check it in the admin portal |
429 | Rate limited | Wait for Retry-After; see below |
| Connection error | Network or proxy | Check egress to v4-api.orangescrum.com:443 |
#Step 2 — client problems
No Orangescrum tools appear at all
In order of likelihood:
- The client was not fully restarted. MCP configs load at startup. Quit completely — reloading the window is not enough.
- The config file is in the wrong place. Paths differ per OS; check them on Client setup.
- The JSON is malformed. A trailing comma silently disables the whole file in most clients. Paste it into a JSON validator.
- Wrong config key. Claude and Cursor use
mcpServers; VS Code usesservers. They are not interchangeable. - Copilot is in ask mode. MCP tools only appear in agent mode.
401 from the client, but curl works
Almost always the header formatting in the Claude Desktop bridge. It must be
"X-API-KEY:YOUR_KEY"
as a single argument with no space after the colon. With a space,
mcp-remote splits it into two arguments and never sends the header.
Claude Desktop: spawn npx ENOENT
Node.js is either not installed or not on the PATH that Claude Desktop
inherits. Verify with node -v and npx -v in a terminal. On macOS, GUI
apps do not read your shell profile — installing Node via the official
installer rather than a version manager avoids this. On Windows, reinstall
Node with "Add to PATH" enabled and reboot.
Tools appear but every call returns 403
The key authenticated but its scopes do not cover that operation. A read-only key shows write tools and rejects them at call time. Ask your account manager to widen the scope, or use a key that already has it.
Calls fail after working for a while
You have hit the rate limit — 120 requests per minute or 5,000 per day, shared with your REST traffic. An assistant doing bulk work burns through this quickly, since there are no batch tools. Give it a dedicated key.
The assistant edits the wrong project or task
Names that look similar to a human look identical to a fuzzy search. Give it the UUID when precision matters, and keep the key read-only until you trust the workflow. The audit trail records everything it did.
A write appears to have failed — should I retry?
Search first. There is no idempotency key, so a retried create that actually succeeded produces a duplicate record.
#Reading the audit trail
Every MCP request is logged with its status code and response time — the same trail as the REST API. When behaviour is confusing, that log is authoritative about what the assistant actually called, as opposed to what it says it called.