For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at /guide/mcp/troubleshooting.md.

MCPAI Connect

Troubleshooting

Q: No Orangescrum tools appear at all

In order of likelihood: 1. You never completed the sign in. Most clients fail quietly if the browser window was closed or timed out. Remove and re add the server to trigger it again. 2. The client was not fully restarted. File based configs load at startup, quit completely, reloading the window is not enough. 3. The config file is in the wrong place. Paths differ per OS; check them on Client setup. 4. The JSON is malformed. A trailing comma silently disables the whole file in most clients. Paste it into a JSON validator. 5. Wrong config key. Claude and Cursor use mcpServers ; VS Code uses servers . They are not interchangeable. 6. Copilot is in ask mode. MCP tools only appear in agent mode .

Q: The sign-in page loops, or authorization never completes

The usual causes: MCP is not enabled for any workspace you belong to. The consent screen has nothing to offer you, so there is nothing to authorize. This is the most common cause on a first connection, have an administrator enable it. Third party cookies or pop ups are blocked for the browser the client opened. Allow them for v4 api.orangescrum.com and retry. A stale session. Sign out at the consent screen and sign back in.

Q: 401 straight after a successful sign-in

Two things produce this: The client is still sending X API KEY . Remove any leftover header X API KEY:... argument from an older mcp remote config, the endpoint does not read that header any more, and its presence can stop the bridge from attempting OAuth at all. The consent did not record a workspace. If the flow was interrupted at the workspace picker, the token exists but has no context behind it. Re authorize and complete the picker.

Q: The handshake fails immediately after OAuth succeeds

If sign in clearly worked but the connection dies at initialize , the client is probably offering a newer MCP spec revision than the server accepts. It negotiates 2025 11 25 , 2025 06 18 , 2025 03 26 and 2024 11 05 . This looks like an auth failure and is not one. Mention the client version when you report it.

Q: A tool returns 403 naming a scope

For example "requires the mcp:sprints.write scope" . The token authenticated fine; you simply did not grant that capability. Re authorize and approve the scope. If it is not offered on the consent screen at all, your workspace is not allowed to grant it, an administrator has to widen the workspace's allowed scopes first.

Q: 403 with insufficient_scope for mcp:use

mcp:use is the base gate every request needs. A client that authorized without it cannot call anything. Remove the connection and add it again, approving the base scope this time.

Q: The assistant can't see a project you know exists

The token is bound to one workspace , the one picked at consent, and carries your own permissions inside it. A project in a different workspace, or one you do not have access to, is invisible. Connect a second time and pick the other workspace.

Q: Calls fail after working for a while

The rate limit: 120 requests per minute, 5,000 per day , returned as JSON RPC 32500 with HTTP 429 . It is counted per IP address , not per user or per token, so colleagues behind the same office NAT or VPN share one bucket, and someone else's bulk run can rate limit you. An assistant doing batch work burns through it quickly, since there are no bulk tools.

Sign-in loops, tools that never appear, 403s on scopes and workspaces, and the errors that look like auth problems but are not.

Work top-down: prove the endpoint is reachable, then look at the OAuth flow, then at the client.

#Step 1, is the server reachable?

Run this on the same machine as the client. It sends no token, so 401 is the healthy answer:

bash

curl -i -sS -X POST https://v4-api.orangescrum.com/mcp/partner \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"ping","id":1}'

Result	Meaning	Next
`401` + `WWW-Authenticate: Bearer realm="MCP"`	Server is up and speaking OAuth	The problem is client-side, step 2
`429`	Rate limited	See rate limits
Connection error or timeout	Network or proxy	Check egress to `v4-api.orangescrum.com:443`
Anything else	Unexpected	Send the full response to support

Then check discovery resolves, clients cannot start without it:

bash

curl -sS https://v4-api.orangescrum.com/.well-known/oauth-authorization-server

#Step 2, the OAuth flow

No Orangescrum tools appear at all

In order of likelihood:

You never completed the sign-in. Most clients fail quietly if the browser window was closed or timed out. Remove and re-add the server to trigger it again.
The client was not fully restarted. File-based 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 uses servers. They are not interchangeable.
Copilot is in ask mode. MCP tools only appear in agent mode.

The sign-in page loops, or authorization never completes

The usual causes:

MCP is not enabled for any workspace you belong to. The consent screen has nothing to offer you, so there is nothing to authorize. This is the most common cause on a first connection, have an administrator enable it.
Third-party cookies or pop-ups are blocked for the browser the client opened. Allow them for v4-api.orangescrum.com and retry.
A stale session. Sign out at the consent screen and sign back in.

401 straight after a successful sign-in

Two things produce this:

The client is still sending X-API-KEY. Remove any leftover --header X-API-KEY:... argument from an older mcp-remote config, the endpoint does not read that header any more, and its presence can stop the bridge from attempting OAuth at all.
The consent did not record a workspace. If the flow was interrupted at the workspace picker, the token exists but has no context behind it. Re-authorize and complete the picker.

The handshake fails immediately after OAuth succeeds

If sign-in clearly worked but the connection dies at initialize, the client is probably offering a newer MCP spec revision than the server accepts. It negotiates 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

This looks like an auth failure and is not one. Mention the client version when you report it.

#Step 3, permission errors

A tool returns 403 naming a scope

For example "requires the mcp:sprints.write scope". The token authenticated fine; you simply did not grant that capability.

Re-authorize and approve the scope. If it is not offered on the consent screen at all, your workspace is not allowed to grant it, an administrator has to widen the workspace's allowed scopes first.

403 with insufficient_scope for mcp:use

mcp:use is the base gate every request needs. A client that authorized without it cannot call anything. Remove the connection and add it again, approving the base scope this time.

Everything returns 403 after working fine

The workspace entitlement was disabled or revoked. That takes effect on the very next request rather than at token expiry, so a working connection can stop mid-session. Ask an administrator to confirm MCP is still enabled.

The assistant can't see a project you know exists

The token is bound to one workspace, the one picked at consent, and carries your own permissions inside it. A project in a different workspace, or one you do not have access to, is invisible. Connect a second time and pick the other workspace.

#Step 4, client and usage problems

Calls fail after working for a while

The rate limit: 120 requests per minute, 5,000 per day, returned as JSON-RPC -32500 with HTTP 429.

It is counted per IP address, not per user or per token, so colleagues behind the same office NAT or VPN share one bucket, and someone else's bulk run can rate-limit you. An assistant doing batch work burns through it quickly, since there are no bulk tools.

spawn npx ENOENT (mcp-remote bridge)

Node.js is either not installed or not on the PATH the client 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.

The sign-in never re-prompts after I revoked access

The mcp-remote bridge caches tokens in ~/.mcp-auth; other clients use the OS keychain or their own profile directory. Remove and re-add the server in the client to force a clean flow.

A checklist write fails with a bad group id

The per-work-item tools need the work item's group instance id, not the catalog group id. Have the assistant call get_work_item_checklist first and use the ids from that response.

The assistant sets a status that doesn't stick

Workflow statuses are configured per project. Point the assistant at list_task_statuses for the project before it writes, rather than letting it guess at "Done" or "In Progress".

The assistant edits the wrong project or task

Names that look similar to a human look identical to a fuzzy search. Give it the uniq_id when precision matters, and keep the grant 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 behavior is confusing, that log is authoritative about what the assistant actually called, as opposed to what it says it called.

#Still stuck?

🔐Re-check the auth model

Scopes, token lifetimes and the full error table.

✉️Contact support

Include the failing tool name, the status code, the WWW-Authenticate header if there is one, and the approximate time.