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).GETandDELETEanswer405. - 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 anid) are acknowledged with202and no body. - Protocol versions:
2024-11-05,2025-03-26(default), and2025-06-18.initializereportsserverInfo.name: "saq"and thetoolscapability 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
Originheader is sent it must behttps://saq.no, and theHostheader must match. Native and cloud clients (Claude Code, Cursor, VS Code, Copilot Studio, the MCP inspector's proxy) send noOriginand 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.
- 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.
- In Copilot Studio, open the agent, select Tools, then Add a tool → New tool → Model Context Protocol.
- 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. - Under authentication choose API key, Type: Header, and enter
Authorizationas the header name. Select Create. - On Add tool, create a new connection. The value asked for is sent as the whole header, so enter
Bearer saq_YOUR_TOKEN: the wordBearer, a space, and the token. Select Add to agent. - 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
Originheader 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, locationHeader, nameAuthorization, 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/listbelow.
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.