Connect your AI to Sortd

MCP (Model Context Protocol) lets an AI assistant use Sortd directly — read the mailbox, task emails onto boards, prioritise lists, draft and (if you allow it) send replies. Sortd hosts the server; you connect your assistant and approve access once in the browser. Two minutes, no key, no code.

1. Connect your client

The hosted endpoint speaks MCP over Streamable HTTP:

https://api.sortd.com/mcp

The default auth is OAuth: your client opens a Connect Sortd page in the browser, you sign in with your normal Sortd account and approve the scopes listed on the consent screen — that approval is the permission grant, no API key involved. Clients that can send headers (CLIs, config files) can use an API key instead.

claude mcp add --transport http sortd https://api.sortd.com/mcp

claude mcp add --transport http sortd https://api.sortd.com/mcp \
  --header "Authorization: Bearer sk_live_…"

{
  "mcpServers": {
    "sortd": {
      "url": "https://api.sortd.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_…" }
    }
  }
}

{
  "mcpServers": {
    "sortd": {
      "type": "http",
      "url": "https://api.sortd.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_…" }
    }
  }
}

2. Try it

Ask the assistant something that exercises the connection:

• "Which Sortd boards can you see?" — walks whoami → list_teams → list_boards.
• "Find the renewal thread from Jane and make it a task on Support / To do." — search_email_threads → create_task_from_email.
• "Re-order my To do list by urgency." — list_tasks + classify_email, then reorder_task per card.
• "Draft a reply saying Thursday works." — create_email_draft; the draft waits in Gmail for you to send.

The full tool list, grouped by scope: MCP tool catalog.

3. Put it on a schedule

The connector really earns its keep on a schedule: "every hour, check for new mail and file anything urgent onto the Support board" is one sentence to your assistant. Claude Cowork and ChatGPT can both run the connector on recurring tasks — recipes, cadences and the scopes to grant a scheduled agent are on the Automate page.

Using an API key instead (CLIs & headless)

For clients that can't run a browser sign-in — scripted CLIs, servers, config-file clients — create a key in the Sortd app: open Settings (the cog, bottom-left), select the API tab, name the key and click Generate. The scopes you tick play the same role as the OAuth consent screen: the assistant only ever sees the tools those scopes allow, and the server enforces them again on every call. The secret (sk_live_…) is shown once; store it now.

A sensible starter set for an assistant: tasks.read, tasks.write, boards.read, lists.read, email.metadata.read, ai.classify, and drafts.write if it should prepare replies. Sending has its own ladder — see Drafts & sending.

How authorisation works

• Scopes are the contract — whether they came from the OAuth consent screen or an API key's tick-boxes. A tool outside the granted scopes isn't listed and can't be called. Tools that span two resources need both — e.g. create_task_from_email requires tasks.write + email.metadata.read.
• Tools carry annotations (readOnlyHint, destructiveHint, idempotentHint) that your client's own permission UI uses to decide what to auto-allow and what to confirm with you. Sends, deletes and secret rotation are flagged destructive.
• Sending is opt-in by scope, never implied. Without a send scope the assistant can at most create drafts for you to review — and email.reply grants a send that structurally cannot reach anyone outside the thread.
• Retries are safe. Send tools accept an idempotency_key; task linking and reorder are idempotent by design.

Can my assistant watch my webhooks?

Not directly. Webhooks are Sortd calling your HTTPS endpoint — and a chat assistant (Claude, ChatGPT, a Cowork session, a scheduled task) is a client, not a server: it has no public URL for Sortd to deliver to. Three patterns that do work:

• Poll on a schedule with get_new_email. The server keeps a per-connection cursor, so a scheduled run simply asks "what's new since I last checked?" — no state in the assistant, no Gmail quota spent, headers-only. The tool's contract (at-least-once delivery, daily check-in, the new_mail_expired recovery) is in its description, so the model handles the edge cases itself. Full contract: Poll for new mail.
• Bridge through a small service you host. Your endpoint receives the webhook (signed, retried) and acts — calls the Sortd API back, files a row somewhere the assistant reads, or triggers your own agent run. This is the real-time option.
• Bridge through Zapier — Sortd's Zapier triggers receive the events and can push them wherever your assistant will look next.

Rule of thumb: assistants pull; servers push. Use MCP for the pulling and webhooks for the pushing, and meet in the middle with a schedule or a bridge — ready-made bridge patterns for n8n, Make, Pipedream, Zapier and self-hosted agents are in the AI guides.

Sessions — audit & disconnect

Each connected assistant gets a session on its first initialize. You can list them (client name, version, declared capabilities, last seen) and revoke any one — the client must re-initialize to continue.

# list connected assistants
curl "https://api.sortd.com/mcp/sessions" -H "Authorization: Bearer sk_live_…"

# revoke one
curl -X POST "https://api.sortd.com/mcp/sessions/mcps_…/revoke" \
  -H "Authorization: Bearer sk_live_…"

Under the hood (for the protocol-curious)

It's plain JSON-RPC — you can drive it with curl. initialize returns an mcp-session-id header; present it on subsequent calls.

curl -i -X POST "https://api.sortd.com/mcp" \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
        "params": { "protocolVersion": "2025-03-26",
                    "clientInfo": { "name": "curl", "version": "0" }, "capabilities": {} } }'

curl -X POST "https://api.sortd.com/mcp" \
  -H "Authorization: Bearer sk_live_…" \
  -H "mcp-session-id: mcps_…" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

Every MCP tool proxies the corresponding REST v2 route in-process — same validation, same scope checks, same audit trail, same webhooks. MCP can't do anything REST can't.

Next: put the connector on a schedule, browse the full MCP tool catalog, or wire up webhooks so your own systems hear what the assistant does.

App menu paths verified September 2026 — vendors rename these periodically; the connector URL and flow are unchanged when they do.