Incentives LLM — API & MCP

A grounded behavioral-economics, incentive-design, and perverse-incentives intelligence layer. Same retrieval pipeline behind a REST API and an MCP server.

Authentication

Create a key at /admin/api-keys and send it as a bearer token:

Authorization: Bearer ilab_xxxxxxxxxxxx

REST endpoints

POST /api/public/v1/search

Pure vector retrieval. Cheap, no LLM call.

curl -X POST https://www.theincentiveslab.com/api/public/v1/search \
  -H "Authorization: Bearer ilab_…" \
  -H "Content-Type: application/json" \
  -d '{ "query": "principal-agent problem in sales comp", "k": 6 }'

POST /api/public/v1/answer

Retrieval-augmented answer with inline [n] citations.

curl -X POST https://www.theincentiveslab.com/api/public/v1/answer \
  -H "Authorization: Bearer ilab_…" \
  -H "Content-Type: application/json" \
  -d '{ "query": "How does loss aversion shape executive comp?", "deep": false }'

Response: { answer, citations: [{ n, title, similarity, document_id }], model }

GET /api/public/v1/health

No auth. Returns service version and current models.

MCP server

Streamable HTTP MCP at https://www.theincentiveslab.com/mcp. Works in Claude Desktop, Cursor, and any MCP-compatible client.

Tools exposed

• search_incentives — raw retrieved snippets
• answer_incentives — cited synthesized answer
• list_dimensions — filterable dimension tags

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "incentives-llm": {
      "url": "https://www.theincentiveslab.com/mcp",
      "headers": {
        "Authorization": "Bearer ilab_…"
      }
    }
  }
}

Cursor

Settings → MCP → Add new MCP server:

{
  "incentives-llm": {
    "url": "https://www.theincentiveslab.com/mcp",
    "headers": {
      "Authorization": "Bearer ilab_…"
    }
  }
}

Rate limits

• /search — defaults to 60 req/min per key (configurable).
• /answer — ~10 req/min per key (heavier LLM call).
• 429 responses include Retry-After.

Errors

• 401 missing/invalid/revoked key
• 403 key missing required scope (search · answer · mcp)
• 402 upstream credits exhausted
• 429 rate limit
• 500 unexpected error (logged in usage)