# Troubleshooting

> Tools not appearing, 401s, Node.js problems and rate limits — the things that actually go wrong.

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/mcp/troubleshooting

---
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:

```bash
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:

    1. **The client was not fully restarted.** MCP configs load at startup.
       Quit completely — reloading the window is not enough.
    2. **The config file is in the wrong place.** Paths differ per OS; check them
       on [Client setup](https://helpdesk.orangescrum.com/guide/mcp/clients).
    3. **The JSON is malformed.** A trailing comma silently disables the whole
       file in most clients. Paste it into a JSON validator.
    4. **Wrong config key.** Claude and Cursor use `mcpServers`; VS Code uses
       `servers`. They are not interchangeable.
    5. **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.

## Still stuck?

- [Check the REST path](https://helpdesk.orangescrum.com/guide/api/authentication): If REST also fails, the problem is the key, not MCP.

- [Contact support](mailto:support@orangescrum.com): Include the failing tool name, the status code and the approximate time.