# MCP Server Troubleshooting > Common issues when connecting AI assistants to ZopNight's MCP server — 401 errors, missing org_id, write refusals, missing tools, rate limits, and how to resolve them. Source: https://zop.dev/developer-docs/integrations/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](https://zop.dev/docs/integrations/mcp-server/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](https://zop.dev/docs/integrations/mcp-server/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: ```bash claude mcp add zopnight MCP_SERVER_URL -t http -H "Authorization: Bearer MCP_PAT" ``` See the [Claude Code setup guide](https://zop.dev/docs/integrations/mcp-server/claude-code) for full instructions.