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

Every tool is a capability from one registry, shared with the REST API and the CLI: same names, same inputs, same responses. Scopes: read, write, spend (uses credits), post (publishes). A key only reaches the scopes it was created with.

tool	scope	what it does
`capabilities_search`	read	Find capabilities by what you want to do (for example "people who liked a post" or "pause a signal").
`capabilities_schema`	read	Exact input schema (JSON Schema) for one capability, plus its scope, whether it spends credits, and whether it returns a job_id.
`get_workspace`	read	This workspace's name, plan, credit balance (credits are the meter for sweeps, checks, renders, and pulls), and the scopes of the key you are using.
`get_playbook`	read	The out-of-the-box playbook for this workspace: the current signal list, the recommended loop (refresh, poll, act, mark), and the spending rules.
`get_trust`	read	What Oetzi is allowed to do on its own in this workspace, per action kind (post:<platform>, reply, video, topics): rung 0 asks first, rung 1 does it after a window unless told no, rung 2 does it and reports.
`set_trust`	write	Move one action kind to a rung, or reset every kind to 0 ("ask me again").
`hold_post`	write	Hold a post Oetzi scheduled on its own (rung 1, "unless you say no"): it goes back to a draft and waits for a tap.
`list_lessons`	read	What this workspace has taught Oetzi by reacting to its work: standing rules from rejected or edited post drafts (the drafter reads these every time), notes on rendered videos, and the 👍/👎 record on matched conversations grouped by signal and by reason.
`forget_lesson`	write	Remove one standing post rule or video note so it stops shaping future drafts.
`get_competitor_report`	read	How the market talks about each competitor in the Brain over the last 90 days: matched conversations that name them, how many were complaints, how many were hot, which platforms, three recent examples with lead ids, and the people who were in those threads (feed them to list_people or record_outreach).
`get_knowledge_graph`	read	The workspace as a graph: the brand node, the segments it serves, the content angles it owns, the competitors the market names next to it, and the most recently active people, each linked to the hub they engaged around (a competitor's thread, or the brand).
`search_knowledge`	read	What this workspace knows about a question, freshest first: facts the team added, documents from Alexandria and news feeds, events and metrics from the connected stack.
`add_knowledge`	write	Tell Oetzi something it should know and cite: a fact about the product, a number, a customer story, a document.
`list_knowledge`	read	The latest items in the store, newest first, optionally one feed's.
`forget_knowledge`	write	Remove one item from the store.
`list_feeds`	read	The workspace's knowledge feeds: saved Alexandria questions, news searches, and the stack's triggers and polls, with cadence, state, last run and item count.
`set_feed`	write	Create, change or remove a feed.
`run_feed`	spend (credits)	Run one pull feed now instead of waiting for its cadence.
`search_alexandria`	read	Discover which of Alexandria's providers and capabilities answer a question (research papers, developer docs, government records, finance, podcasts, jobs, and 90 more), or browse the catalogue by provider or category.
`pull_alexandria`	spend (credits)	Run one Alexandria capability and put what comes back in the store as documents (or events).
`list_voices`	read	Every voice this workspace can write in: name, kind (brand writes as the company and says "we", user belongs to one person and says "I"), which is the default, how many pieces of real writing each was measured from, and where each was extracted from.
`get_voice`	read	One voice in full: its topography document (the markdown that says what this writer ALWAYS does, OFTEN does, RARELY does and NEVER does, with the counts behind each band), the writing it was measured from, and what a person said about past drafts (sounds like me / not me).
`list_voice_presets`	read	The voices Oetzi ships, for a workspace with no writing to extract from yet.
`create_voice`	write	Add a voice to this workspace.
`set_voice`	write	Replace one voice's topography with the markdown you pass (up to 8,000 chars).
`update_voice`	write	Rename a voice, change whose it is, switch it between brand and user, or make it the workspace default.
`delete_voice`	write	Remove a voice and the writing stored against it.
`extract_voice`	spend (credits)	Read somebody's actual writing and draw the voice from it.
`add_voice_samples`	write	Add writing to a voice (posts, emails, anything they actually wrote, 20 to 2,000 chars each).
`remove_voice_sample`	write	Drop one piece of writing from a voice by id (ids come from get_voice).
`pull_voice_samples`	write	Pull recent posts from an account this workspace has connected, into a voice.
`generate_voice_doc`	write	Redraw a voice's topography from the writing already stored against it, plus (for a brand voice) the posts this workspace approved.
`preview_voice`	read	Write one throwaway sample in a voice, so a person (or you) can hear what it sounds like before anything real is drafted in it.
`check_voice`	read	Check a draft against what was counted in a voice, before anyone reads it.
`rate_voice`	write	Say whether a drafted reply or post sounded like the writer.
`list_signals`	read	List this workspace's listening signals: the natural-language definitions of the conversations being watched, with id, status, cadence, and the platforms each one watches.
`get_signal`	read	One signal in full: definition, status, cadence, the platforms it watches, the platform queries it compiles to, and its last runs.
`set_signal_status`	write	Pause or resume a listening signal.
`set_signal_platforms`	write	Choose which platforms one signal watches, e.g.
`run_signal_now`	spend (credits)	Sweep one signal now across every platform it watches, instead of waiting for its cadence.
`get_leads`	read	Fetch qualified conversations from this workspace: public posts scored for buying intent, each with the post content (truncated at 1,200 chars, use get_lead for full detail), 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.
`get_lead`	read	Full detail for one conversation: untruncated post content, thread context, author profile fields, reply draft variants, enriched contact when present, and current status/feedback.
`get_walk`	read	Today's comment walk: the conversations of the last three days worth a comment, best first (fresh, an author with reach, an open question, close to the buyers, never an author we commented on this fortnight), each with the comment already written to paste under the thread (one true thing from what we know, one question at most, no link, no pitch).
`walk_step`	write	One step of the comment walk on one conversation: done (the comment was posted by hand, the conversation is contacted and the outreach recorded), skip (dismissed, with a reason that becomes a standing rule when it reads like one), later (shortlisted), or rewrite (a new comment with your note, free).
`mark_lead`	write	Update a conversation's workflow status after acting on it: 'contacted' when outreach was sent, 'saved' to shortlist, 'dismissed' to skip.
`rate_lead`	write	Quality feedback on a conversation, the same 👍/👎 as the human inbox, feeding the signal-tuning loop.
`draft_reply`	spend (credits)	Generate two reply variants for a conversation, each with a why-this-angle note, written for its platform norms and in one of the workspace's voices (pass `voice`, or let the default reply).
`enrich_lead`	spend (credits)	Resolve a LinkedIn conversation's author to a verified contact: full name, title, seniority, company, and a verified business email (MoltSets, then Firecrawl's LinkedIn enrichment).
`translate_post`	read	Render a non-English conversation in English: the post body and its thread context, tone and handles preserved.
`lookup_linkedin`	spend (credits)	Any LinkedIn URL to what is known about it, through Firecrawl's LinkedIn enrichment (the URL is routed to the team's Alexandria providers: Apollo, FullEnrich, Data Legion).
`list_people`	read	People who interacted with posts this workspace matched: the authors of conversations and, once engager pulls run, the people who liked, reposted, replied to, or quoted them.
`get_person`	read	One person in full: every platform identity, this workspace's interactions with them (each with the post and the conversation it became), verified contacts, tags, and every outreach recorded against them.
`resolve_person`	spend (credits)	Resolve a person to a verified contact (name, title, company, business email, mobile on premium) through the vendor waterfall: MoltSets, then Firecrawl's LinkedIn enrichment (Apollo, FullEnrich, Data Legion through Alexandria).
`tag_person`	write	Add or remove free-text tags on a person for this workspace (for example "champion", "do-not-contact", "q4-list").
`record_outreach`	write	Report that you contacted a person: the channel, what you sent, the outcome, and who you are.
`pull_engagers`	spend (credits)	Pull the people who engaged with a post (liked, reposted, quoted, replied, commented) into the people graph, then read them with list_people.
`list_geo_questions`	read	The buying questions this workspace tracks across AI engines (ChatGPT, Gemini, Perplexity, Grok, Google AI Mode), as a user would type them.
`get_share_of_model`	read	The latest share-of-model board: for every tracked question, which engines mentioned this workspace, at what rank, which competitors they named instead, and the sources they cited.
`run_geo_check`	spend (credits)	Ask every configured AI engine each tracked question now and record who they recommend.
`list_content`	read	Short-form video ideas, drafts, renders and carousels in this workspace.
`generate_content`	spend (credits)	Propose short-form video ideas from what the market is saying: this workspace's hottest matches by default, or one conversation (lead_id), one signal (signal_id), posts that already earned attention (proven), or a brief.
`render_content`	spend (credits)	Approve an idea and render it at a length.
`reject_content`	write	Reject an idea before anything is rendered.
`revise_content`	spend (credits)	Revise content with feedback instead of accepting or rejecting it.
`get_video_performance`	read	How the video loop is doing, by template arm: proposed, rejected, rendered, accepted and published counts over the window, hook pairs, the hooks that went live, and the benchmark (first 20 published videos across the arms).
`create_persona`	write	Start the workspace's persona: four portrait candidates of one synthetic creator, generated from a look you describe (or from the brain when you don't).
`choose_persona`	write	Make one portrait candidate the workspace's persona, with a name and an ElevenLabs voice.
`create_loop_kit`	write	Make the workspace's background loop kit: three short generated high-speed loops (an endless runner, a first-person corridor, a marble run, described generically, never a real game) that the sound-off and split-screen formats cut from.
`recut_demo`	spend (credits)	Cut a finished demo again without recording: another wallpaper, the presenter bubble on or off.
`create_demo`	write	Start a product demo video from a docs page and a demo login.
`get_demo`	read	One demo session: the agent's declaration (what it understood, its click plan step by step, open questions), the action log while it records, and the video when done.
`list_demos`	read	Demo sessions in this workspace, newest first, with status and video links.
`answer_demo`	write	Answer the questions the agent asked in its declaration (or add facts it should know).
`confirm_demo`	spend (credits)	Confirm the declared plan and record.
`cancel_demo`	write	Cancel a demo that has not finished.
`list_social_accounts`	read	Accounts this workspace can publish through: natively connected X, LinkedIn, Bluesky, and a Postiz account with its channels (TikTok, Instagram, YouTube, Threads, and more).
`list_posts`	read	The post queue: drafts waiting for review, approved and scheduled posts, what was published (with URLs), failures with their error.
`get_post`	read	One queued or published post in full, with its topic, rationale, reply target, media, and publish result.
`create_post`	write	Put a post you wrote into the queue as a draft (or already approved) for a platform: x, linkedin, bluesky, threads, or any Postiz channel provider (tiktok, instagram, youtube).
`make_card`	write	Draw or redraw the graphic on a queued post: a stat card (a real number, optionally a series as a line), a quoted line with its platform, one sharp sentence, or a workspace screenshot, on a wallpaper.
`draft_posts`	spend (credits)	Draft original posts in the workspace's voice for one platform, from a topic: a row on the Topics list (topic_id, see list_topics), something trending today bridged to the buyers (trending: true, see list_trends), a share-of-model plan item (plan_item_key from get_share_of_model), a brief, verbatim hot-match phrasings (lead_ids), or a seed post to riff on.
`run_newsroom`	write	Draft today's story for every page now instead of waiting for the morning: on each platform with a plan on, every connected page (a presence's channel, or the account) gets its best article published today (the workspace's newsroom rules decide the window) from its own site feeds, as a post with the article's own picture (never a map), its first two paragraphs verbatim and the link as the first comment.
`set_newsroom_rules`	write	The newsroom's standing rules for this workspace, read and set.
`review_post`	write	Approve, reject, or edit a queued post.
`cross_post`	write	Take one queued or published post and draft it for other platforms: the same claims, numbers, and links reshaped to each platform's length and norms, with the original's graphic or video carried over.
`publish_post`	post (credits)	Publish a queued post under the workspace's name through the connected account for its platform (Postiz for its channels).
`post_reply`	post (credits)	Reply to a matched conversation on its platform, under the workspace's connected account (X, LinkedIn comment, Bluesky).
`get_posting_plan`	read	The posting plan per platform: how many original posts a week Oetzi drafts (0 = off, capped per platform), whether each draft waits for approval or publishes itself (publish_mode approve \| auto), the credits a month that implies, and when it last ran.
`set_posting_plan`	write	Set the posting plan for one platform: posts_per_week (0 = off, clamped to the platform's daily ceiling times seven) and publish_mode.
`get_post_performance`	read	The scoreboard: what each published post did (impressions, likes, comments, shares, clicks, from Postiz analytics, the platform, or the workspace's own engager pulls at 24h, 72h, and 7 days), ranked by engagement score, with averages by topic kind, by content angle, and by platform, plus the latest 7-day snapshot per channel.
`refresh_post_metrics`	write	Read a published post's numbers right now (Postiz analytics for Postiz posts, the latest engager pull otherwise) and store them as the post's manual snapshot.
`set_angle_state`	write	Rest a content angle from the posting rotation on one platform for a season (about 90 days), or put it back early.
`list_trends`	read	What is being talked about right now that fits this workspace's buyers: today's trend scan (corpus velocity leaders plus a live news search, scored by the judge for ICP fit, each with the bridge line from headline to buyer problem).
`enable_channel`	write	Turn one Postiz channel on or off for this workspace, by channel id from list_social_accounts.
`audit_formats`	write	Read the workspace's last 90 days of posts on every platform it can publish to, including posts published outside Oetzi through Postiz, tag each with the shape it takes (article lead + link, one number, a take, how to, a story, a question, a list, team news, someone's words), and judge the shapes with fair-test rules.
`get_formats`	read	The format playbook the audit wrote (not get_playbook, which is the workspace's signal playbook): per platform, every shape the workspace's posts took, ranked (winner, holding, untested, losing), with the sample each verdict rests on, the best example, the winning shape to lean on, and the cadence the history suggests.
`adopt_formats`	write	Schedule the playbook: set the posting plan on each platform (or the ones named) to the cadence the audit suggests, drafts waiting for a tap.
`list_topics`	read	The Topics list: what this workspace has decided to post about.
`add_topic`	write	Put something on the Topics list.
`set_topic_status`	write	Mark a topic done (it stops drafting), reopen it, or remove it from the list.
`list_rising`	read	What is rising in the conversations Oetzi listens to this week: the corpus of the last seven days clustered by meaning, each cluster with its size against its usual week, which platforms, who is talking (author roles and follower tiers), five example posts, and the judge's fit score and bridge line for this workspace's buyers.
`ask_trending`	read	"What are people saying about X?" Pulls the closest conversations from the last two weeks of the corpus and writes a read: the threads of what is being said, who says it (by role), the tone, and one bridge line to this workspace's buyers.
`get_topic_read`	read	One read from ask_trending (result is null while it runs), or the last twenty reads when read_id is omitted.
`list_post_replies`	read	Replies and comments on posts this workspace published, newest first, each with who wrote it, the text, a permalink, the drafted answer in the workspace's voice, whether it has been handled, and whether Oetzi can post the answer in place (Bluesky today, X and LinkedIn once their apps are registered).
`get_post_reply`	read	One reply to an own post in full: the comment, the person, the post it answers, the drafted answer, how it was handled.
`draft_post_reply`	write	Redraft the answer to a reply on an own post: two variants in the workspace's voice with a why-this-angle note.
`reply_to_comment`	post (credits)	Answer a reply on an own post in place, under the workspace's natively connected account.
`mark_reply_handled`	write	Close a reply on an own post without Oetzi posting: copied (you answered by hand on the platform) or dismissed (no answer needed).
`refresh_post_replies`	write	Check one published post for new replies and comments right now (replies only, free, a few seconds on Bluesky and X, up to a couple of minutes on LinkedIn).
`list_presences`	read	Where this workspace shows up, or should: every presence (a LinkedIn page per city edition, the founder's X profile, a subreddit to be useful in) with why it is recommended, its status (recommended, connected, have_it, creating, deferred, dismissed), what it is linked to, and its content plan (pillars, series, a four-week calendar) once planned.
`discover_presences`	write	Work out where this business should have a presence from its brain (segments, buyers, category) and what is already connected: usually 3 to 6, a page per regional or product segment on the platform where that audience lives, one hub profile, a community where the buyers ask for help.
`set_presence`	write	Decide one presence.
`plan_presence`	write	Write (or rewrite, force: true) the content plan for one presence: 3 to 5 pillars with a share, recurring series, how it sounds here, an honest posts-per-week, and a four-week calendar of concrete working titles.
`get_outcomes`	read	What Oetzi's work got this workspace: clicks on tracked links, replies, signups, and customers, each tied to the conversation or post that earned it.
`record_outcome`	write	Record a win against the thing that earned it: kind 'signup', 'customer', or 'reply', attached to a conversation (lead_id), a published post (post_id), or a tracked link (link_code).
`list_plays`	read	The plays library: every named tactic Oetzi can run for this workspace, each with why it works, what Oetzi does, what the human taps, what one run costs, what to expect, and where it stands right now (ready, running with a receipt, done, blocked with the reason, or coming).
`run_play`	spend (credits)	Run one play from list_plays.
`get_job`	read	State of a background job: status (running \| done \| error), phase (queued \| running \| done \| error), progress when the worker reports it, the result once done, and the error otherwise.
`wait_job`	read	Block until a job finishes, up to 25 seconds per call, then return its state.
`list_events`	read	Events in this workspace after a cursor: conversations delivered (lead.delivered, lead.hot), people discovered, posts published, share-of-model checks, jobs completed, outreach recorded.
`wait_events`	read	Block until at least one event after the cursor lands, up to 25 seconds per call, then return the batch.
`list_webhooks`	read	Webhook subscriptions in this workspace: URL, event types, active flag, last status, failure count.
`subscribe_webhook`	write	Register an https URL to receive events as signed JSON POSTs (header X-Oetzi-Signature = sha256 HMAC of the body with the returned secret).
`unsubscribe_webhook`	write	Remove a webhook subscription by id.

Spending and long work

Tools that spend credits accept dry_run, approved, and max_credits. Without approved: true and a max_credits ceiling they run nothing and return an estimate. Tools marked async return a job_id; wait_job blocks up to 25 seconds per call until it settles.

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.

Scopes

A key carries the scopes its creator picked: read, write, spend, post. tools/list shows every tool regardless, so an agent can see what exists and ask its operator for a wider key. A call outside the key's scopes returns scope_denied.

Events

list_events and wait_events give a push-style loop over MCP without a webhook: conversations delivered, people discovered, posts published, checks completed, jobs settled, outreach recorded, outcomes recorded. Start with list_events and no cursor to learn the current id, then wait_events from it.

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	The tool result carries isError and the error code first: scope_denied, budget_exceeded, insufficient_credits, not_found, invalid_input, rate_limited, conflict, unsupported.