Authentication

Every request to the AI StackWorks MCP server carries a bearer token:

Authorization: Bearer <token>

The token — never a client-supplied id — is the trust boundary. The server resolves it to a tenant and re-filters every record under that tenant, so a card from another project simply returns card not found. Cross-tenant access is a 404, not an error that leaks data.

The two token kinds

Project API key

The developer-facing key, prefixed aisw_. You mint it from the in-app Getting started page (Connect your repo to this project); it is shown once and stored hashed. Regenerate it from the same page to revoke the old one instantly.

A project API key is account-wide, so it names the project it targets in the request:

• as a query parameter on the URL — ?project=<project-slug>, or
• as a header — X-AISW-Project: <project-slug>.

The selector is advisory: it is always re-resolved under the key's own account, so it can never widen access beyond what the key already grants.

{
  "mcpServers": {
    "aistackworks": {
      "type": "http",
      "url": "https://app.aistackworks.com/api/mcp/?project=my-repo",
      "headers": { "Authorization": "Bearer aisw_xxxxxxxxxxxxxxxx" }
    }
  }
}

Dispatch run token

An ephemeral token minted automatically when a card is dispatched to the agent fleet. It is already scoped to a single (account, project), so it ignores the project selector — its tenant comes entirely from the token. You don't manage these directly; they are issued per dispatch for the agents doing the work.

There is no card in the token

A token resolves to (account, project) — not to a specific card. The card an agent works on is task context, passed explicitly as the card_id argument to each card tool and then re-filtered under the token's tenant. This is why one token can drive many cards across a project, and why every card tool takes a card_id.

Fail-closed posture

• No bearer header → 401 Unauthorized.
• Present but invalid or expired token → 401 Unauthorized, rejected at the auth layer before any tool runs. An invalid token is never returned as a tool result.

Keep keys safe

A project API key grants read/write access to that project's records. Treat it like a password — keep it out of source control, and regenerate it from the Getting started page if it is ever exposed.

Next steps

• Tools Reference — every tool and its arguments.
• Getting Started — connect a client from scratch.