Sprawl Sign In

MCP Setup

Sprawl exposes a native Model Context Protocol endpoint so LLM clients (Claude Code, Claude Desktop, Cursor, custom agents) can act on your tasks, checklists, and notes through the same context functions the browser and REST API use.

What you get

  • A single endpoint at POST https://sprawl.today/mcp.
  • Stateless JSON-RPC 2.0 (Streamable HTTP). No sessions, no SSE.
  • Bearer-only auth — Authorization: Bearer <token>. No x-agent-secret required (that header is REST-only).
  • 17 tools spanning task_*, checklist_*, note_*, activity, and whoami. Tool names mirror the sprawl CLI.

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 obeys the task → project → key cascade).
  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 supports the Streamable HTTP transport at the endpoint and pass your token in the Authorization header.

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"
      }
    }
  }
}

Claude Desktop currently only ships with stdio transport in its config UI. To connect it to a remote Streamable HTTP server like Sprawl, wrap the URL with a small bridge (e.g. npx @modelcontextprotocol/mcp-remote) until first-class HTTP support lands.

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" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

A successful call returns the full tool catalogue. Swap tools/list for tools/call + {"name":"task_list","arguments":{}} to exercise a tool.

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.
  • Non-owner key — access is resolved per resource via the cascade task override → project override → key default. You set those overrides from the project side-panel on /tasks and on the agent key itself in /auth-settings.
  • 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.