MCP

Sally supports two MCP patterns:

1. Hosted MCP exposed directly by the Sally API at /mcp
2. Local stdio MCP via the sally-mcp package

For most users, the recommended default is hosted MCP.

Quick decision guide

Choose hosted MCP if you want the cleanest setup, a URL-based MCP server, remote clients connecting directly to Sally, and key management inside the product.

Choose stdio MCP if you want a local CLI process, an older or stricter MCP client that expects stdio, or additional tool families exposed by the local wrapper.

Hosted MCP

Endpoint:

https://your-sally-domain.com/mcp

Authentication uses a Sally hosted MCP key:

Authorization: Bearer sallymcp_...

These keys:

• belong to a real Sally account
• inherit that account’s permissions
• may optionally be restricted to one workspace

Important transport behavior

• hosted MCP uses streamable HTTP transport
• your client should accept text/event-stream
• you must initialize the MCP session before calling tools
• the server issues an Mcp-Session-Id header that you must keep using

Minimal hosted MCP flow

1. initialize
2. notifications/initialized
3. tools/list
4. tools/call

Example initialize request

curl -X POST https://your-sally-domain.com/mcp \
  -H 'Authorization: Bearer sallymcp_...' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "curl-test", "version": "1.0.0" }
    }
  }'

Example tools/list request

curl -X POST https://your-sally-domain.com/mcp \
  -H 'Authorization: Bearer sallymcp_...' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'mcp-session-id: YOUR_SESSION_ID' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Hosted tool families

• workspaces and invites
• clients
• projects and project members
• project statuses
• tasks, labels, todos, and comments
• timesheets

Hosted MCP gotchas

• 406 Not Acceptable — your client is not accepting text/event-stream
• Server not initialized — you called a tool before initialize
• MCP session not found — your session expired or you reused an old session id
• Unauthorized — the key is invalid, revoked, or missing permissions
• Workspace access denied by MCP key restriction — the key is pinned to a different workspace

Local stdio MCP

Required environment:

SALLY_URL=https://your-sally-domain.com
SALLY_USER_API_KEY=atpm_...

Optional restriction:

SALLY_WORKSPACE_SLUG=sally

Run manually:

SALLY_URL=https://your-sally-domain.com \
SALLY_USER_API_KEY=atpm_... \
sally-mcp

Example stdio MCP client config:

{
  "mcpServers": {
    "sally": {
      "command": "sally-mcp",
      "env": {
        "SALLY_URL": "https://your-sally-domain.com",
        "SALLY_USER_API_KEY": "atpm_your_personal_key"
      }
    }
  }
}

Security model

MCP access is only as broad as the Sally user behind the key. Owner-only actions remain owner-only, workspace restrictions still apply, and revoking the key cuts off the client.