Connect an MCP client

Written for

integration-developer

Roles

Requires

An API token (personal token or agent account key)

Feature

mcp

SAQ runs a Model Context Protocol (MCP) server so that AI assistants can read and change tickets, log time, and read client timesheets with the same permissions as the token they hold. This page covers the transport, client setup, and every tool.

Endpoint and transport

• Endpoint: POST https://saq.no/mcp (Streamable HTTP, JSON-RPC 2.0). GET and DELETE answer 405.
• One JSON-RPC message per request. A JSON array (batch) is refused with 400.
• Methods: initialize, ping, tools/list, tools/call. Other methods answer JSON-RPC error -32601. Notifications (messages without an id) are acknowledged with 202 and no body.
• Protocol versions: 2024-11-05, 2025-03-26 (default), and 2025-06-18. initialize reports serverInfo.name: "saq" and the tools capability only; there are no resources or prompts.
• Authentication: Authorization: Bearer saq_YOUR_TOKEN. Cookies are ignored. See Authenticate with API tokens.
• Browser clients: if an Origin header is sent it must be https://saq.no, and the Host header must match. Native clients (Claude Code, Cursor, the MCP inspector's proxy) send no Origin and need nothing extra.

Set up Claude Code or Cursor

An Owner or Admin can copy ready-made snippets from Settings → Channels → MCP setup; the same text is returned by GET /api/w/acme/mcp in a browser session. Replace saq_YOUR_TOKEN with a token you minted.

Claude Code (.mcp.json or your user settings):

{
  "mcpServers": {
    "saq": {
      "type": "http",
      "url": "https://saq.no/mcp",
      "headers": {
        "Authorization": "Bearer saq_YOUR_TOKEN"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "saq": {
      "url": "https://saq.no/mcp",
      "headers": {
        "Authorization": "Bearer saq_YOUR_TOKEN"
      }
    }
  }
}

Aliases

Tool arguments accept human references instead of UUIDs; every alias resolves only within the token's workspace:

An unknown project answers not_found; an unknown kind, state, or person answers invalid.

Tools

The three documentation tools read this public documentation and hold no workspace data, so any token may call them regardless of scope or project restriction.

Results and errors

A successful tools/call returns one text content block whose text is the JSON result:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"01924c3e-6b2a-7d11-9d0e-3a1f4b5c6d7e\"}"
      }
    ]
  }
}

Domain errors (validation, permission, not found, read-only) are returned as a tool result with isError: true and the same { error, message, details } body the REST API uses:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"forbidden\",\"message\":\"This token does not include that scope\",\"details\":{\"scope\":\"write\"}}"
      }
    ]
  }
}

Invalid arguments answer error: "invalid" with details.issues. An unknown tool name answers not_found. Authentication failures and rate limits are HTTP-level (401, 403, 429) with the REST error body, not JSON-RPC results. In a read-only workspace, read tools keep working and write tools answer read_only.

Rate limits

MCP shares the REST budgets: 600 requests per minute per address, 120 per token, and the workspace's plan budget shared by every token. Each request is one JSON-RPC message, so each tool call costs one request. See API conventions.

The context pack

get_context_pack returns a read-only snapshot sized for a model's context window. Every section is permission-filtered, capped at 25 items, and carries truncated: true when more exist; page the rest with search_tickets filters.

Attribution

Tickets and comments created through MCP are stored with source: "mcp". With a personal token, the actor is the person and the record notes that a token acted on their behalf; with an agent key, the actor is the agent account.