Connect an MCP client

The MCP endpoint, how Claude Code, Cursor, VS Code (GitHub Copilot), and Microsoft 365 Copilot are connected, every tool with its arguments and result, error shapes, rate limits, and the context pack.

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 and cloud clients (Claude Code, Cursor, VS Code, Copilot Studio, the MCP inspector's proxy) send no Origin and need nothing extra.
  • There is no OAuth: SAQ is not an OAuth authorization server and publishes no /.well-known/oauth-protected-resource. A client that can only authenticate through OAuth cannot connect; one that can send a static header can.

What every client needs

Whatever the client, the setup is the same three facts: the URL https://saq.no/mcp, the header Authorization: Bearer saq_YOUR_TOKEN, and a token minted for the account that should act (a personal token from Account → API tokens, or an agent account's key from Settings → People → Members). Each person connects with their own token; a shared token would attribute everyone's work to one account. An Owner or Admin can copy ready-made snippets for the file-based clients 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.

Set up Claude Code or Cursor

The two snippets differ in one line: Claude Code requires "type": "http", and Cursor's format has no type field.

Claude Code (.mcp.json in the project, or your user settings):

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

Cursor (.cursor/mcp.json in the project, or ~/.cursor/mcp.json):

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

Set up VS Code (GitHub Copilot)

GitHub Copilot in VS Code reads .vscode/mcp.json in the workspace (or the user profile's mcp.json; MCP: Add Server in the Command Palette writes it). The root key is servers, not mcpServers, and an inputs entry lets VS Code ask for the token when the server starts instead of keeping it in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "saq-token",
      "description": "SAQ API token",
      "password": true
    }
  ],
  "servers": {
    "saq": {
      "type": "http",
      "url": "https://saq.no/mcp",
      "headers": {
        "Authorization": "Bearer ${input:saq-token}"
      }
    }
  }
}

Paste the token, including nothing but the saq_… value, when VS Code prompts for it.

Set up Microsoft 365 Copilot (Copilot Studio)

Microsoft 365 Copilot does not read a configuration file: an MCP server is added as a tool to a Copilot Studio agent, and the agent is then published to Microsoft 365 Copilot and Teams. SAQ meets what Copilot Studio requires from a server: a public HTTPS endpoint, the Streamable HTTP transport (Copilot Studio no longer supports the older SSE transport), and API-key authentication in a request header. SAQ has no OAuth server, so the OAuth 2.0 options in the wizard do not apply; choose the API key.

  1. Mint the token first (a personal token, or an agent account's key). Each person who will use the agent needs their own token; Copilot Studio asks each user for it the first time the agent calls SAQ.
  2. In Copilot Studio, open the agent, select Tools, then Add a tool → New tool → Model Context Protocol.
  3. Enter a Server name, a Server description (the agent's orchestrator reads it to decide when to call SAQ; say what SAQ holds, for example "Tickets, time, and client timesheets in SAQ"), and the Server URL https://saq.no/mcp.
  4. Under authentication choose API key, Type: Header, and enter Authorization as the header name. Select Create.
  5. On Add tool, create a new connection. The value asked for is sent as the whole header, so enter Bearer saq_YOUR_TOKEN: the word Bearer, a space, and the token. Select Add to agent.
  6. Test the agent in Copilot Studio with a prompt that needs SAQ ("what is overdue for me"), then publish it to the channels your tenant allows.

Things to know:

  • Copilot Studio calls SAQ from Microsoft's cloud. The calls carry no Origin header and need no allowance on SAQ's side; they count against the token's rate limit and the plan's budget like any other client.
  • MCP servers in Copilot Studio are Power Platform connectors. A Power Platform data policy that blocks custom connectors also blocks the SAQ tool; the tenant's Power Platform administrator controls that.
  • Microsoft's Agent 365 registration of external MCP servers (a preview feature of the Microsoft 365 admin center) accepts the same shape: authentication type APIKey, location Header, name Authorization, and a public server URL. Once an administrator approves the registration, the server appears in Copilot Studio's registry and, per Microsoft, in VS Code, Claude Code, and GitHub Copilot CLI.
  • The tool names, descriptions, and argument schemas Copilot Studio shows are those from tools/list below.

The menu names above follow Microsoft's documentation at the time of writing; Microsoft's documentation is authoritative for its own product.

Other clients

Any other MCP client that supports Streamable HTTP with a static header connects with the same URL and header. The MCP inspector reaches SAQ through its own proxy, so it needs nothing extra either.

Aliases

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

Argument Accepts
ticket, source, target ACME-184 or a ticket UUID
project project key (website) or UUID
kind, state workflow key (bug, in_progress) or UUID
assignee, viewer a person's email in this workspace, a UUID, me, or none

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

Tools

tools/list names only the tools the workspace can use: while the workspace's Time and billing feature is off (Settings → Features), log_time, get_timesheet, close_period, create_billing_run, and get_bank_balances are left out, and calling one anyway answers the feature_off error below. See Turn features on or off.

Tool Scope Arguments Returns
search_tickets read q, creator (part of the creator's name or email address), project, kind, state, stateCategory (open/closed), assignee, viewer, queue (inbox), billingClientId (UUID or none), billingPolicy, labelIds [UUID], priorityIds [UUID], due (overdue/week/none), parentId (UUID for one ticket's sub-tickets, or none for top-level tickets only), staleDays (1–36500), blocked (boolean), unbilledOnClose (boolean), cursor, limit (≤50) { items, nextCursor } of ticket summaries, newest activity first
get_ticket read ticket The ticket page: fields, viewers, comments, events, attachments, links, GitHub links, time, permissions. comments is omitted when no audience is readable; time is omitted for client users
list_boards read none { boards: [{ id, name, key }] }: the workspace board plus each visible project
get_board read Same filters as search_tickets without cursor and limit, plus closedWithinDays (1–365) to keep only tickets closed that recently in closed columns { columns: [{ state, total, older, tickets, nextCursor }] }; older counts the closed tickets the window left out
create_ticket write (triage when project is omitted) title (required), description, project, kind, state, assignee, priorityId, billingClientId, labelIds, startDate, dueDate, estimateMinutes, parentId; repeat (rule, duration, leadDays, endsOn, as in the recurring tickets API) makes it a recurring series anchored on startDate, which is then required together with project The new ticket summary; without project it lands in the Inbox. With repeat, the first occurrence, its recurrence set
update_ticket write ticket plus any of title, description, kind, state, assignee, priorityId, labelIds, startDate, dueDate, billingClientId, billingPolicy, billingMode, billingDescription, estimateMinutes, parent (a ticket id, or null to detach) The updated ticket page; each field is checked against the owner's permissions
move_ticket write (triage when leaving the Inbox) ticket, project, kind, assignee, billingClientId, confirmReset The ticket page after the move
add_comment write ticket, body (≤50 000 characters), audience (shared/internal/staff), mentions [UUID, ≤20], attachmentIds [UUID, ≤20], stateId (UUID, moves the ticket in the same step), minutes (≥1, logs that time on today's date in the same step) The created comment; mentions become viewer grants
link_tickets write source, target, kind (blocks/relates/duplicates/parent; parent makes source a sub-ticket of target) { id } of the link; { "id": null } for parent, which is not an edge
log_time write ticket, spentOn (YYYY-MM-DD), minutes (≥1), startedAt (HH:MM), note, billable (default true) { id } of the entry, logged as the token's owner
close_period – none Always refused: forbidden, "Period close is a UI-only action in v1"
create_billing_run – none Always refused: forbidden, "Billing runs are a UI-only action in v1"
get_bank_balances read none { banks, projectUsage }; balances need client-wide billing document access, otherwise only projectUsage
get_timesheet read documentId or clientId With documentId: the document's metadata and content (encoding: "base64" for PDF, "utf-8" for HTML and CSV). Without: the list of documents the owner may download, optionally for one client
get_inbox read review (boolean) { items }: the shared Inbox (triage scope, unrestricted token) or, with review: true, the restricted review items the owner may read
get_context_pack read none The context pack described below
link_github write ticket, repo (owner/name), url, sha (7–40 hex) and/or pr (integer) The stored GitHub link
search_docs any query (required), audience (user/admin/integration-developer), section, feature, limit (≤20) { hits }: matching documentation sections with url, title, heading, text, audience, roles, and permissions
get_doc any page (a path such as time/register-time, /docs/time/register-time/, or the full URL) One documentation page with its sections
list_docs any none The documentation table of contents

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. A tool of a feature the workspace has turned off returns an error result with error: "feature_off" and details.feature, the same code the HTTP API uses.

{
  "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.

Section Content
mine Open tickets assigned to the owner
overdue Open tickets past their due date
dueSoon Open tickets due within 7 days
inbox { count, oldestCreatedAt } for the shared Inbox, or null when the token cannot see it
blocked Open tickets with unresolved blockers, each with its blocker list (own truncation flag)
stale Open tickets with no activity for 14 days (staleDays: 14 in search_tickets)
time The current period: periodStart, periodEnd, loggedMinutes, estimateMinutes; null while Time and billing is off, and unbilledOnClose and the bank sections are then empty
unbilledOnClose Open deliverable tickets (billed when closed) with unbilled time
banks, bankProjectUsage Time bank balances with projected overage, and per-project usage
github GitHub links on the tickets above

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.