AI & MCP

TEASE ships a Model Context Protocol (MCP) server so an AI agent — Claude, or any MCP-compatible client — can read your analytics and operate your workspace on your behalf. You point the client at one endpoint, authenticate with a scoped al_live_* key, and the agent discovers everything it can do at runtime. No SDK, no per-tool wiring, no glue code.

The server speaks JSON-RPC 2.0 over a single POST /mcp. Every call is authenticated, scope-gated, and isolated to the workspace that owns the key. Message bodies are never stored.

Connect in 60 seconds

curl -X POST https://app.tease.link/api/admin/api-keys \
  -H "Authorization: Bearer $TEASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "claude-desktop", "scopes": ["read"] }'

{
  "mcpServers": {
    "tease": {
      "type": "http",
      "url": "https://app.tease.link/mcp",
      "headers": {
        "Authorization": "Bearer al_live_a1b2c3d4_…"
      }
    }
  }
}

Protocol

The endpoint is JSON-RPC 2.0. One HTTP POST /mcp carries exactly one JSON-RPC object. Authentication is the same Bearer scheme as the rest of the API.

A request that omits or presents an invalid key is rejected with HTTP 401 before any method runs. Malformed JSON returns a JSON-RPC parse error (see Errors).

initialize

The handshake. The client announces itself; the server returns its protocol version, capabilities, and identity. Send this once per session before any other method.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "claude-desktop", "version": "1.0.0" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "tease" }
  }
}

After initialize, well-behaved clients send the notifications/initialized notification. Notifications carry no id and the server answers with HTTP 202 and an empty body.

tools/list

Returns the catalog: every tool the agent is allowed to call, as name + description + inputSchema only. This is the single source of truth — clients discover capabilities here rather than from a hardcoded list, so the catalog can grow without a client change.

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_stats",
        "description": "Read workspace performance stats for a period.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "period": { "type": "string", "enum": ["7d", "30d", "90d"] }
          },
          "required": []
        }
      }
    ]
  }
}

Each entry follows the standard MCP tool shape:

tools/call

Invoke one tool by name with arguments matching its inputSchema. The result is wrapped in an MCP content block.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_stats",
    "arguments": { "period": "7d" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "{ \"revenue\": 4820.50, \"subscribers\": 173 }" }
    ],
    "isError": false
  }
}

The arguments object must satisfy the tool's inputSchema. Any required property that is missing is rejected before the tool runs.

get_stats returns the full revenue.sources block. Every real-source, organic, and pending row includes a required seven-counter Full Attribution funnel object: new, old, ftl, paid, paid_after, ftl_paid, and entered.

Errors

Protocol-level failures use standard JSON-RPC error codes plus one TEASE-specific code for scope. The shape is always:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": { "code": -32601, "message": "Method not found: 'tools/foo'" }
}

A 401 (HTTP, not JSON-RPC) means the Bearer key was absent, malformed, or revoked — it is returned before any method is dispatched.

Scopes & permissions

Every tools/call is gated by the scopes on the key that made the request. Scope is enforced server-side at call time — a key can never reach a tool above its grant, regardless of what the agent attempts.

For the full key lifecycle — minting, the one-time secret, rotation, and revocation — see Authentication.

Tool catalog

The catalog is discovered at runtime via tools/list — names, descriptions, and inputSchema only. The groups below are a high-level map of what areas the agent can work in, not a behavioral spec; for the exact, current set of tools and their arguments, always read tools/list.

Attribute your fans

Raise source + country coverage on your organic fans. Every fan who arrived through a tracked link already has an exact source — the click told us. The rest are organic, and the only evidence of where they came from is what they wrote in their DMs. TEASE attributes them in two tiers:

1. Automatic sweep — a server model reads captured conversations and fills source + country for every fan it can. This is the floor, and it runs on its own.
2. Your own agent (this) — point your Claude at the residual the sweep couldn't resolve and let it read each conversation in full. A strong model on the raw thread is the precision tier: it lifts coverage toward complete, whales first.

Both tiers write the same record, so an agent-set attribution shows up in your Fans grid and fan cards exactly like the automatic one — with a dashed "presumed" badge until the evidence is strong enough to promote it to the money-canon.

The loop — three tools

A write-scoped key unlocks these (mint one on the API keys page — see Authentication):

Ask in natural language — "attribute my top organic fans by source and country" — and the agent works the list, reads each thread, and writes graded guesses straight into your tables. A graded guess beats a blank; it never fabricates a place or platform the fan didn't imply.

Trust & safety

The MCP server is built so you can hand an agent real capability without handing over your account.

FAQ

Next steps

• Authentication — key format, scopes, rotation, revocation.
• Smart Links — the trackable links many MCP tools operate on.
• API Reference — the REST surface behind the same al_live_* keys.