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.

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

MCP write is currently disabled across the platform while it rolls out, so every mutating tool call gets this answer today whatever your organisation is set to. Contact us if you want to be part of the rollout.

Once write support reaches your organisation, this error means the organisation's Write access tier (Settings → Organisation) is below the tier the tool needs — or, for a tier-3 tool, that your token is not bound to an organisation. See How to Connect for the tiers and what each admits.

"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 tier enables

Expected. Your AI tool discovers tools via tools/list, which advertises only what your token can actually call. No PAT issued today is bound to an organisation, and an unbound token is advertised read tools only.

Tier-1 and tier-2 write tools can still be called by passing org_id explicitly — ask your agent to call the tool by name. Tier-3 tools require a bound token and cannot be called by any token that exists today. This resolves when tokens start carrying their organisation.

"rate limit exceeded" (rate_limited)

Too many MCP calls from your token in a short window. This one is retryable — wait for the interval in the Retry-After header and try again. The budget is per token, so a runaway agent slows itself down, not your colleagues. The budget currently applies to write calls; read calls are not throttled today.

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

Retries are not deduplicated. The idempotency_key argument is accepted but nothing acts on it today: a retried deploy_service creates a second deploy; a retried create_provisioning_job creates a second job and real cloud spend. Read back the current state before retrying any write.

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 you are using HTTP transport, not SSE or WebSocket.

Claude Code shows "not authenticated"

Claude Code's HTTP transport may try OAuth before using headers. Use the CLI command with -t http flag to force HTTP transport:

claude mcp add zopnight <url> -t http -H "Authorization: Bearer <token>"

See the Claude Code setup guide for full instructions.