MCP Setup

What you get

• A single endpoint at POST https://sprawl.today/mcp.
• MCP 2026-07-28 over Streamable HTTP: stateless JSON-RPC 2.0, no initialize handshake, no sessions, no SSE stream. Older clients that open with initialize are not supported.
• Bearer-only auth — Authorization: Bearer <token>. No x-agent-secret required (that header is REST-only).
• 21 tools spanning task_*, checklist_*, workspace_*, assignment_event_show, activity, and whoami. Tool names mirror the sprawl CLI.
• MCP Events: one event type, sprawl.assignment , fired when a checklist item is assigned to the token's agent key or that assignment is removed. See Assignment events.

1. Generate a token

Tokens are minted from your agent-key settings page. Each token is bound to one agent key, and you can have several active at once (one per client is a clean default).

1. Open your auth settings. If you are not signed in, you will be sent through login first.
2. Pick an agent key (your owner key gives the token full access; a non-owner key is confined to the workspace it is bound to).
3. Name the token (e.g. claude-desktop) and click Generate token.
4. Copy the revealed string immediately. It is only shown once — if you lose it, revoke the row and generate a new one.

2. Configure your client

Point any MCP client that implements protocol revision 2026-07-28 (Streamable HTTP with per-request _meta) at the endpoint and pass your token in the Authorization header. Check your client's release notes for that revision first: a client still on the initialize handshake is refused with an error naming the supported version, and stdio bridges built for the older transport (such as mcp-remote) will not connect.

Claude Code (CLI)

claude mcp add --transport http sprawl \
  https://sprawl.today/mcp \
  --header "Authorization: Bearer YOUR_TOKEN_HERE"

JSON config (Cursor, custom clients)

Most HTTP-capable MCP clients accept a config shape like this:

{
  "mcpServers": {
    "sprawl": {
      "url": "https://sprawl.today/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

3. Smoke test

Before plugging the token into a client, confirm the endpoint sees it:

TOKEN=<paste your token>
curl -s -X POST https://sprawl.today/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list",
       "params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28",
                          "io.modelcontextprotocol/clientCapabilities":{}}}}' | jq

A successful call returns the full tool catalogue. Every request carries its protocol version and client capabilities in params._meta, mirrored into the MCP-Protocol-Version and Mcp-Method headers. To exercise a tool, send tools/call with {"name":"task_list","arguments":{}} alongside _meta, and add Mcp-Name: task_list. A tool that refuses (not_found, forbidden, validation) answers with a result flagged isError: true and the reason in structuredContent.error.

Assignment events

server/discover advertises the events capability. events/list describes sprawl.assignment, which events/poll or a webhook subscription delivers, for the token's own agent key in one Workspace:

• Send {"name":"sprawl.assignment","arguments":{},"cursor":null} to get a starting cursor, then poll with the cursor each answer returns. Add arguments.workspace_id to watch another Workspace (with a cursor of its own: a cursor is only good in the Workspace and Project it came from), and maxEvents (up to 100) or maxAgeMs to bound a backlog.
• Each event carries identifiers only: change (assigned or removed), the item, task and Workspace ids, the item's assignment_revision and who made the change. Read the item with checklist_show before acting; assignment_event_show reads an event back by id.
• truncated: true means events were skipped (the cursor outlived the 30-day retention, or maxAgeMs cut them): reconcile with checklist_by_state {"assignee":"me"} , which lists every incomplete item assigned to you.
• A client that cannot poll (ChatGPT) calls events/subscribe with {"mode":"webhook","url":"https://…","secret":"whsec_…"} as delivery. The URL must be public HTTPS on port 443 and must first echo a signed verification challenge; then each event arrives as one Standard Webhooks–signed POST. The lease lasts up to 7 days, never past the token's own validity: subscribe again before refreshBefore to renew it, or call events/unsubscribe. An agent key holds at most 10 live subscriptions. Revoking the token stops delivery; each key's subscriptions are listed (host only) in /auth-settings.

Permissions

The token's bound agent key decides what the MCP client can see and do:

• Owner key — full access to every task, project, and setting on your account. Without a project key, calls land in the workspace the owner key is bound to (pick it in /auth-settings).
• Non-owner key — bound to one workspace: it reaches every task there at its default permission and nothing outside it. Both the workspace and the level are set on the key in /auth-settings.
• Project key (x-project-key) — confines the client to one project, in whichever workspace that project lives, provided the agent key can reach it.
• Theme settings are deliberately not exposed as MCP tools — an LLM has no business mutating your appearance.

Revoke or rotate

• Revoke a single token — delete the row from /auth-settings. The next request from any client using it fails immediately.
• Revoke every token under a key — deleting a non-owner agent key cascades to all tokens issued under it.
• Rotating an agent key's secret does not invalidate MCP tokens. MCP only reads the bearer; only deleting the token row revokes MCP access.