API reference

MCP tools

The tool catalog

The public tool catalog — including each tool's input schema and required scopes — is available without authentication at GET /v1/mcp/tools. Over MCP, tools/list returns only the tools your token's scopes can actually execute.

Utility tools

Available with mcp:tools:read (invocation additionally requires mcp:tools:call):

lucra.scopes.list — the public API scope taxonomy and bundled grants
lucra.mcp.tools.list — this catalog, with per-tool access for your token

Domain tools

Domain tools read live workspace data. Each requires mcp:tools:call plus one of the listed actor scopes, and returns JSON as MCP text content:

Tool	Actor scope (any of)	Returns
`lucra.organization.get_context`	`brand:organization:read`, `partner:organization:read`	Organization identity and partner status
`lucra.creators.search`	`brand:creator:read`, `partner:creator:read`	Roster creators — name, handle, status, tags
`lucra.programs.list`	`brand:programs:read`, `partner:programs:read`, `creator:programs:read`	Programs with status, visibility, and type
`lucra.products.list`	`brand:products:read`, `partner:products:read`, `creator:products:read`	Products with type, vendor, and status
`lucra.ads.list`	`brand:ads:read`, `partner:ads:read`	Non-archived paid campaigns with platforms and status
`lucra.submissions.list`	`brand:submissions:read`, `partner:submissions:read`, `creator:submissions:read`	Submissions with review state
`lucra.analytics.summary`	`brand:analytics:read`, `partner:analytics:read`, `creator:analytics:read`	Aggregate spend, clicks, impressions, and outcomes
`lucra.finance.summary`	`brand:finance:read`, `partner:finance:read`, `creator:finance:read`	Transaction totals by status
`lucra.creator.profile.get`	`creator:creator:read`	The authenticated creator's profile

Inputs and bindings

List and search tools accept two optional arguments: limit (1–100, default 20) and query (search text, max 120 characters). Organization tools require the token to be bound to an organization, and lucra.creator.profile.get requires a creator binding — calls on an unbound token return JSON-RPC error -32602.

Calling a tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "lucra.programs.list",
    "arguments": { "limit": 10, "query": "spring" }
  }
}

Results come back as MCP text content containing JSON, for example:

{
  "programs": [
    {
      "id": "spring-creator-spark",
      "name": "Spring Creator Spark",
      "status": "Live",
      "visibility": "open",
      "programType": "paid_ads"
    }
  ]
}