MCP Server Troubleshooting

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

401 Unauthorized

Your token is invalid or expired. Go to Developer Settings and create a new token.

”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.

Claude Code shows “not authenticated”

Check the token before anything else: when an Authorization header is configured and the server rejects it, Claude Code reports the connection as failed rather than falling back to OAuth. Also confirm the server was added with -t http, since without it the URL is treated as a command to run:

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

See the Claude Code setup guide for full instructions.