mcp

MCP troubleshooting

The usual suspects, and how to clear them.

The server doesn't appear in my client

  • Check the config file path for your client and OS, and that the JSON is valid — a trailing comma or missing brace silently disables the block.
  • Fully quit and reopen the client (not just close the window) so it re-reads the config.
  • If you already had servers configured, make sure you merged into the existing object rather than replacing it.
  • If npx isn't on the PATH your client sees, use an absolute path, e.g. "command": "/usr/local/bin/npx".

Tools show up but every call says Unauthorized

  • You probably minted an ext or api token. Mint a new mcp token at zaaidev.com/dev/settings/tokens.
  • The token may be revoked — revoked tokens show struck-through on the tokens page. Mint a fresh one.
  • Test it directly:
terminal
ZAAI_API_TOKEN="zaai_mcp_..." npx -y @zaai-dev/mcp

InsufficientCredits / 402

  • Top up at zaaidev.com/dev/settings/billing — packs apply immediately.
  • Or wait — your monthly grant resets on the 1st (UTC).
  • Check your balance with the free whoami tool.

ProjectNotFound / OutOfScope / ProjectArchived

  • ProjectNotFound — the id isn't in your org. Copy the UUID from the workspace URL (/dev/projects/<uuid>).
  • OutOfScope — your token's project allowlist doesn't include it. Mint a token without project scope, or add the project.
  • ProjectArchived — unarchive it in workspace settings.

CaptureNotFound

The capture id doesn't exist or is in a project your token can't see. Run list_captures first to get valid ids.

The connection drops mid-conversation

  • Confirm Node 20+ with node --version.
  • Check your client's MCP logs for the underlying error.
  • Transient network blips retry automatically; a true outage surfaces as a network error reaching the workspace.

I upgraded and tools are missing

npx -y @zaai-dev/mcp pulls the latest on first launch only — restart your client to pick up a new release. To pin a version, use "args": ["-y", "@zaai-dev/mcp@0.6.2"].

Still stuck? Email support@zaaidev.com, or revisit tokens and the MCP overview.