docs · for agents

MCP server

Oetzi exposes your qualified conversations as an MCP (Model Context Protocol) server, so any agent that speaks MCP can pull qualified, intent-scored conversations and action them: Claude Code, Claude Desktop, Cursor, or your own agent built on any MCP client library. The loop an agent runs is simple: poll for new hot conversations, act on each one, mark it contacted so the human inbox stays in sync.

Endpoint & auth

The server speaks Streamable HTTP and is stateless: every request is authenticated with a workspace API key, created in Settings. Keys are scoped to one workspace, an agent working three products uses three keys.

endpoint

https://www.oetzi.ai/api/mcp
Authorization: Bearer oetzi_...

Connect from Claude Code

terminal

claude mcp add --transport http oetzi https://www.oetzi.ai/api/mcp \
  --header "Authorization: Bearer oetzi_YOUR_KEY"

Connect from Claude Desktop, Cursor, or any client

mcp config (JSON)

{
  "mcpServers": {
    "oetzi": {
      "type": "http",
      "url": "https://www.oetzi.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer oetzi_YOUR_KEY"
      }
    }
  }
}

Tools

tool	what it does
`get_leads`	Fetch qualified conversations: post content, author, platform URL, intent score (0-100), band (hot/warm/review), a why-it-matched rationale, and a ready-to-send reply draft when available. Filters: `signal_id`, `status`, `band`, `since` (ISO 8601), `sort` (newest / oldest / score), `limit` (max 50).
`get_lead`	Full detail for one conversation: untruncated content, thread context, draft variants, enriched contact, current status.
`list_signals`	The workspace's listening signals, with ids for filtering get_leads.
`set_signal_status`	Pause or resume a signal remotely. Draft signals still need compilation in the app first.
`mark_lead`	Set a conversation's status after acting on it: `contacted`, `saved`, or `dismissed`. This is what keeps the human inbox in sync with agent work.
`rate_lead`	The same 👍/👎 as the human inbox, feeding the tuning loop. `good` confirms a match, `not_relevant` marks a miss and dismisses the match. Labels tune the signal's judge overnight, so rate accurately, with a `reason` when one fits.
`get_workspace`	Workspace name, plan, and quota usage for the current period.
`get_playbook`	The out-of-the-box playbook: the workspace's current signal list plus the recommended loop. Agents should call it at the start of every session, it regenerates on each call, so it doubles as the way to refresh the signal list.
`enrich_lead`	LinkedIn conversations only: resolves the author to a verified contact (name, title, seniority, company, verified business email) via a multi-vendor waterfall. Cached per conversation, so repeat calls are free. Available when contact enrichment is enabled for the deployment.

The agent loop

You don't need to design the loop yourself: the server ships it. get_playbook returns a ready-to-follow playbook containing the workspace's live signal list and the recommended cadence, and the same text is exposed as the MCP prompt playbook for clients that surface prompts. A minimal agent brief is just:

agent instructions

You work qualified conversations from Oetzi.
At the start of each session, call get_playbook on the
oetzi MCP server and follow it. It covers everything:
refreshing the signal list, polling for new hot conversations,
using reply drafts, enriching LinkedIn matches to verified
contacts, and marking conversations contacted when done.

Because the playbook regenerates on every call, an agent that re-reads it always sees signals the team added, paused, or renamed since the last session, no redeploys or prompt edits needed.

Good citizenship

Leads are pushed as they qualify, so polling more often than every few minutes buys nothing. Statuses and ratings are shared with the human inbox: a conversation your agent marks contacted or rates good shows up that way for the whole team, and a not_relevant rating dismisses it for everyone.

Machine-readable index

Agents exploring the site cold should fetch /llms.txt (the discovery index) and /llms-full.txt (the complete reference, generated from the same tool definitions this server ships, so it is always current). Point a crawling agent at either and it has everything on this page.

Errors

status	meaning
401	Missing, invalid, or revoked API key.
403	The key's workspace has no active plan.
tool error	Bad arguments or an unknown id, the tool result carries isError with a message.