Troubleshooting MCP
Resolve common connection, authentication, permission, and workspace errors.
# Troubleshooting MCP
## The client opens a login flow unexpectedly
No bearer token reached the server. For a headless client, confirm that `SCHEDULER_ZERO_API_KEY` exists in the agent process and that the client sends it as `Authorization: Bearer ...`.
## `401 Unauthorized`
The credential is missing, invalid, expired, or revoked. OAuth clients should reconnect and complete sign-in again. API-key clients should create a personal key (`szp_...`) under **Settings → Personal → API keys**. Keys starting with `sz_` are no longer accepted.
## `403 Forbidden`
The credential is valid but lacks the permission required by the selected tool. A key can do only what both its access settings and your own current permissions allow. Widen the key's access in **Settings → Personal → API keys**, or ask an Organization admin for the permission. Creating or rotating keys and deleting or transferring an Organization or Workspace are only available in the web app.
## The tools point at the wrong workspace
- OAuth session: run `list_workspaces`, verify the consent grant, and supply an authorized `workspaceId`.
- API-key session: run `list_workspaces` and pass the intended `workspaceId` on each call. If the Workspace is missing, the key's access does not include it, you no longer have access to it, or its Organization has blocked the key.
## A new REST operation is missing
MCP tools are declared in the capability registry and projected from the generated catalog. A new REST endpoint does not automatically create a capability. Check the [tool reference](/mcp/tools), verify the API and Worker revisions, and refresh the client's cached tool catalog.
Scheduler Zero