mcp

Authentication & tokens

The MCP server authenticates with a bearer token you mint in the workspace. It's the same token system the extension uses — just a different kind.

Mint an MCP token

  1. 1
    Go to zaaidev.com/dev/settings/tokens.
  2. 2
    Mint a token and pick the mcp kind — not ext (extension) or api.
  3. 3
    Copy the token. It looks like zaai_mcp_… and is shown once — the mint screen also pre-fills config snippets for you.

Provide it to the server

The server reads the token from the ZAAI_API_TOKEN environment variable. Your client's config sets it (see Claude Code, Cursor). To test by hand:

terminal
ZAAI_API_TOKEN="zaai_mcp_..." npx -y @zaai-dev/mcp

Scopes & the API URL

  • Tokens are scoped to your org. You can optionally restrict a token to specific projects when minting it — calls outside that allowlist return OutOfScope.
  • The server talks to https://zaaidev.com by default. Only override ZAAI_API_URL for local/preview testing — a prod token won't validate against a different host.
  • Revoke a token any time on the tokens page; revoked tokens stop working immediately.

keep it secret

A token grants read access to your workspace data. Treat it like a password — don't commit it to a repo. If one leaks, revoke it and mint a new one.