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