MCP troubleshooting

Most MCP issues come down to authentication, which server you’re talking to, or where that server is pointed. Work through these in order.

Tip

First, establish which server you have. dst mcp wires you to the hosted endpoint; a command entry pointing at an mcp binary is the self-run binary. They register different tools, and half of “the tool is missing” reports are really “that tool lives on the other server.” See the reference for both catalogs.

The server refuses to start

DESTESI_API_KEY is required in stdio mode

In stdio mode (the default, used by desktop clients) the server has no per-request header to authenticate with, so it requires a process-wide key. Set DESTESI_API_KEY to an identity PAT (idn_pat_…) in your client’s env block.

{
  "mcpServers": {
    "destesi": {
      "command": "/path/to/mcp",
      "env": { "DESTESI_API_KEY": "idn_pat_…" }
    }
  }
}

DESTESI_API_URL is required in --http mode (cannot default to localhost:8080)

In HTTP mode the server refuses to fall back to the localhost default — that almost always means DESTESI_API_URL is unset and every tool call would fail with connection refused. Set DESTESI_API_URL explicitly to your Destesi API base URL (for example https://api.destesi.io) before starting with --http.

Authentication errors

missing or invalid Authorization header (HTTP 401)

The HTTP/SSE transport rejects any request that doesn’t carry a bearer token. The client must send Authorization: Bearer <token>. If you wired the server with dst mcp, this header is set for you — try re-running dst mcp to refresh the token. If you configured the client by hand, confirm the header is present and the token is non-empty.

workspace_list fails but branching tools work

workspace_list exists only in the self-run binary; if you are on the hosted endpoint there is no such tool to call. In the binary, it is served by the identity service and needs an identity PAT (idn_pat_…). A product-scoped personal key authorizes the Snap branching tools but not the workspace-discovery path. Switch to an identity PAT — the same token dst login stores — and the whole surface works from one credential.

Tip

Run dst login then dst whoami to confirm you have a valid session, then dst mcp to register the server with that identity. This is the simplest way to guarantee the right token type.

list workspaces failed on a multi-host setup

If your identity service runs on a different host than the Destesi API, workspace_list may be hitting the wrong base URL. Set DESTESI_IDENTITY_API_URL to the identity service’s base URL. On a single-host setup you can leave it unset — it defaults to DESTESI_API_URL.

Tool-call errors

branch is not ready (status: …) from remote_url

remote_url only returns a DSN for a branch in ready status. Right after clone or fork, the branch is still provisioning. Call wait with the operation ID those tools return, then call remote_url once it reports ready.

timed out after Ns waiting for operation …

wait polls until the branch is ready or the timeout elapses (default 120 seconds). For a large source that legitimately takes longer to materialize, pass a higher timeout_seconds. If it keeps timing out, check the operation directly — status on the branch, or remote_show on the connector to confirm the source is healthy and syncing.

lineage cycle detected at …

branch_lineage walks parent pointers and stops if it revisits a branch, rather than looping forever. This indicates a corrupted parent chain for that branch; the lineage up to the cycle is still valid. Inspect the affected branches with status and recreate the branch from a clean fixture or remote if needed.

create snap failed / create connector failed (status 4xx/5xx)

These surface the API’s status code. A 4xx usually means a bad argument — a missing required field (dsn for a Postgres remote, s3_bucket for an S3 remote), an unknown workspace_id or connector_id, or a parent_snap_id that isn’t ready. Double-check the arguments against the reference. A 5xx is a server-side issue — retry, and verify the source is reachable.

missing 'workspace' or missing 'workspace_id'

Three argument names are in play and they are not interchangeable. Connect action tools and the product families (Drive, Deploy, ImageGen, Commerce, TTS, Chat, Studio, Design) take workspace — your workspace slug. Snap, Review, and Preview tools on the self-run binary take workspace_id — the ws_… id. The hosted endpoint names that same id argument identity_workspace_id.

Call workspace_list (self-run binary) to get both forms for every workspace you belong to. A few Studio tools require workspace and workspace_id in the same call.

not_connected or insufficient_scope from a connect_* tool

These come from Connect, not from MCP. not_connected means the workspace has no active connection for that provider — authorize it at connect.destesi.io and retry. insufficient_scope means the connection exists but was authorized without the scopes this action needs; reconnect the provider and grant them.

The agent doesn’t see the tools you expect

No Destesi tools at all

• Confirm the server is registered with your client. For Claude Code, re-run dst mcp; for desktop clients, check the mcpServers entry points at the correct mcp binary path.
• Restart the client after changing its MCP configuration — most clients only read it at startup.
• For a hand-configured stdio client, run the binary in a terminal with the same env to confirm it starts without the refusals above before pointing the client at it.

Snap and Preview tools appear, but no Drive / Deploy / Commerce / TTS / Chat / Studio / Design tools

Two possibilities, in order of likelihood:

1. You’re on the hosted endpoint. It only ever registers Snap, Preview, and Connect tools. The product families exist only in the self-run binary — no configuration change to the hosted endpoint will surface them.
2. The base URL is unset. In the self-run binary each family is gated on its own variable (DRIVE_API_URL, DEPLOY_API_URL, and so on). An unset variable disables that family silently by design — the server logs <PRODUCT>_API_URL unset — … tools disabled at startup and keeps serving everything else. Check the server’s startup log, set the variable, and restart.

No connect_* tools

The catalog is fetched once, at boot. If Connect was unreachable at that moment, the server logs connect action catalog unavailable, skipping connect tools and registers none — it does not retry, and it does not fail to start. Restart the server once Connect is reachable.

The same applies to catalog changes: a provider or action added in Connect after the server started will not appear until you restart it.

A specific tool is missing (query, workspace_list, fixture_*, branch_lineage)

These are split across the two servers. query exists only on the hosted endpoint. workspace_list, the fixture tools, and branch_lineage exist only in the self-run binary. Preview also differs: six tools on the hosted endpoint, four in the binary. Check the reference before assuming parity.

Still stuck?

Verify the basics from the reference: the right server, the right transport, an identity PAT, and DESTESI_API_URL pointing at your Destesi API. Because the Snap tools mirror the dst snap CLI verbs, you can reproduce any failing Snap operation with the CLI to isolate whether the problem is the MCP layer or the underlying operation. Most other families have no CLI equivalent — for those, reproduce the call against the product’s own API instead.