MCP Server Troubleshooting

Common issues when connecting to ZopNight's MCP server and how to resolve them.

401 Unauthorized

Your token is invalid, expired, or revoked. The response includes a WWW-Authenticate: Bearer challenge naming the resource metadata URL — an OAuth-aware client should walk the discovery chain and re-consent. For a PAT, go to Developer Settings and create a new token.

If your client does not see the WWW-Authenticate header at all, it is almost certainly not posting to the /mcp-server prefix. The challenge is emitted at every MCP subpath (/mcp-server/mcp, /mcp-server/sse, …) via prefix matching; a request to / gets a plain 401 with no challenge.

OAuth: invalid_grant on refresh

Your refresh token has been retired. Two common causes:

• Reuse after the 60-second in-row grace window. Refresh tokens rotate on every use. Presenting a retired refresh token triggers family kill on reuse (RFC 9700 §4.14.2) — every refresh token in that lineage is revoked and the user must re-consent. Two parallel processes sharing a refresh token race each other into this.
• The user revoked the Connected App. Revocation via Connected Apps in ZopNight is instant and irreversible for that token family. Re-run the authorization code flow to reconsent.

OAuth: insufficient_scope on a write

Your role allows the action, but the OAuth grant does not carry the write scope the tool needs. Two options: re-consent with the missing scope, or ask an admin to widen the client's default scopes. This is the OAuth equivalent of token_scope for PATs; both mean "the token is narrower than the identity."

OAuth: ChatGPT / Claude append /mcp to the resource URL

Some clients derive the OAuth resource value from the MCP URL by rule rather than by discovery, and will POST an authorization request naming <host>/mcp-server/mcp even though the advertised resource is <host>/mcp-server. The ZopNight token endpoint accepts either form — resource comparison is prefix-based against the mount — so this should not break auth. If it does, upgrade the client, or paste the exact URL from Settings → Organisation verbatim (do not add a /mcp suffix).

"MCP server is not enabled for this organisation"

An admin needs to enable MCP for this organisation. Go to Settings → Organisation and toggle MCP Server to ON. See the overview for detailed steps.

"org_id is required"

The tool call is missing the org_id argument. Ask your AI assistant to call list_organisations first, then use the org ID in subsequent calls.

A mutating tool called without org_id is refused earlier, by the gateway, and reads missing org_id in tool arguments instead. The fix is the same.

"you don't have access to this organisation"

You are not a member of the requested organisation, or you have been removed. Check your organisation membership in ZopNight.

"MCP write is not enabled for this organisation" (mcp_write_not_allowed)

The tool you called changes something, and it was refused. This is a permanent refusal for that call — retrying will not help.

The usual cause is the organisation's Write access setting (Settings → Organisation) being below what the tool needs. See How to Connect for the settings and what each admits.

It is not the only cause, and this is worth knowing before you spend time on the setting. The write gate refuses for several distinct reasons — the organisation's level, a platform-level switch outside your organisation's control, and the capabilities the acting token carries — and all of them return this identical response. Which one applied is deliberately not disclosed to the caller, so an agent cannot map out what to ask for.

So if the setting already looks high enough for the tool you called, raising it further will not help: ask support to check the platform-level switch and your token's capabilities rather than probing.

"this API token is not scoped for this action" (token_scope)

Your role allows the action but this token was not minted with the capability it needs. Re-mint the token from Developer Settings with the right Write capabilities ticked, or use one that already has them. Distinct from rbac_denied: there, the person lacks the permission; here, the token does.

"forbidden" (rbac_denied) on a tool you expected to work

The organisation allows this tool, but your role does not allow the underlying action. MCP grants nothing the UI does not: if you cannot do it in ZopNight, your agent cannot do it either. Ask your agent to call get_my_permissions to see what your token can actually do, then ask an admin for the role you need.

My AI tool does not list the write tools my Write access setting enables

Two causes.

Your organisation’s Write access setting does not admit them. tools/list advertises only what is actually callable, so a tool the setting excludes is not listed.

Your token carries no capabilities. tools/list advertises a write tool only if the token itself was minted with the capability that tool needs. A token created before the Write capabilities picker existed carries none, and is advertised read tools only. Re-mint it from Developer Settings, ticking the capabilities you want it to have. Reads are unaffected either way.

"rate limit exceeded" (rate_limited)

Too many MCP calls in a short window. This one is retryable — wait for the interval in the Retry-After header and try again. The budget is per user, not per token, so two tokens you minted share one bucket; a runaway agent slows you down rather than your colleagues.

"policy table not loaded; retry" (policy_not_ready)

The gateway is still starting and cannot check permissions yet, so it refuses rather than guessing. Retry in a few seconds.

A write returned an error, but it also happened

Possible, and worth checking before you retry. A write can succeed and still fail to reach you — a timeout, a dropped connection, a cancelled turn.

Do not assume a retry is deduplicated. Passing idempotency_key does let the server replay the original response instead of re-running the write, for 24 hours, and it collapses two concurrent calls that share a key into one execution. But that protection lives in the server instance that handled the first call: a retry routed to another replica misses it, and no backend behind these tools deduplicates on the key. So a retried deploy_service can still create a second deploy, and a retried create_provisioning_job a second job and real cloud spend.

Read back the current state before retrying any write. Reusing a key with different arguments is rejected rather than silently replayed, so the key is safe to reuse for a genuine retry of the same call.

A change I made through MCP is not showing up

Give it a moment before assuming it failed. Schedules and overrides are picked up by the scheduler on its next pass (about a minute). Deploys and Provisioning jobs are asynchronous — poll for status; a deploy commonly takes 20 minutes and can take up to about 35. Start and stop are confirmed against real cloud state, so a resource may sit in starting or stopping for a while.

Connection refused or timeout

Make sure you are using the correct Server URL. The URL is shown in the Developer Settings page after creating a token, and in Settings → Organisation when MCP is enabled. Ensure your client is set to Streamable HTTP — not WebSocket, and not STDIO, which expects a local process rather than a remote server.

Client reports "not authenticated" or fails to connect

Two causes cover most of these:

• Bad token. When an Authorization header is pre-configured and the server rejects it, several MCP clients (including Claude Code) report the connection as failed rather than falling back to OAuth discovery. Verify the PAT is current, or clear the header and let the client run OAuth.
• Wrong transport. ZopNight's MCP server is Streamable HTTP, not STDIO. Clients that default to STDIO treat the URL as a command to run. Force HTTP transport in the client's config — for example, the Claude Code CLI needs -t http:

claude mcp add zopnight MCP_SERVER_URL -t http -H "Authorization: Bearer MCP_PAT"

Per-client setup snippets live in the product docs at zop.dev/docs/zopnight/integrations/mcp and zop.dev/docs/zopday/integrations/mcp.