MCP server

Add Mimeo to Claude Code, Cursor or any MCP client, and your agent can operate the whole instance — author flows, write emails, define segments, look people up, read reports, push definitions.

The server runs on your instance, at /mcp. There's nothing to install locally and nothing to keep updated: the tools an agent sees always match the version your instance is actually running.

Installation

Create a token under Settings → API, then:

claude mcp add --transport http mimeo https://your-instance.com/mcp \
  --header "Authorization: Bearer mm_your_token"

Or, in an .mcp.json committed to a repo:

{
  "mcpServers": {
    "mimeo": {
      "type": "http",
      "url": "https://your-instance.com/mcp",
      "headers": { "Authorization": "Bearer ${MIMEO_TOKEN}" }
    }
  }
}

The token is the same one the HTTP API and the CLI take, and it has full access — keep it in a secret manager rather than a committed file.

What it can do

Two things it deliberately won't do

Flows are whole documents

There is no insert_step, no move_step, no delete_step. Those exist in the admin UI, where a human clicking + is placing exactly one step. An agent's flow edit nearly always spans several steps at once, and a per-step tool is a way to leave a flow half-restructured between two validated states — with real people running through it in between.

So the loop is: get_flow → rewrite the definition → validate_flow → dry_run_flow → save_flow. Ids are preserved exactly as given and never renumbered; leave the id off a genuinely new step and the instance mints one above every id that flow has ever used.

Attaching an email is a decision, and it gets asked

Every tool that attaches an email takes email_source, and it is required with no default:

An agent that omits it is guessing on the operator's behalf about whether a later edit reaches one send or twenty — so the server refuses rather than picking. And a broadcast never shares: create_broadcast doesn't offer shared in its schema, and the server refuses it even if asked. What one broadcast sent should stay what it sent.

fork_email is the repair when something is shared that should have been a copy: it splits one holder off onto a row of its own and leaves every other holder on the original.

Sorting out a library that has filled up

Every broadcast mints its own email row, so the library accumulates rows that existed for one send. list_emails takes the same filter the admin listing does:

list_emails  used_in: ["broadcasts", "sequences", "flows", "flows_one_off"]
             used_mode: "any" | "all" | "none"

used_mode: "none" answers "what does nothing point at any more". flows means reached by a flow at all — including through a sequence it starts — while flows_one_off means only a flow's own send_email step. Every row also carries where_used, so you can see what editing it would reach before you edit it.

Files or MCP?

Both go through the same API and the same validation, so they can't disagree. Use the CLI and a definitions repo for anything that should be reviewed as a diff and live in git history — building a flow, rewriting a sequence, editing copy. Use MCP for questions and for changes that don't need a commit: looking someone up, counting a segment, reading a report, firing a test event.

Protocol notes

Streamable HTTP, protocol version 2025-06-18, negotiating down to 2025-03-26 and 2024-11-05. POST /mcp answers with a single JSON object; GET and DELETE return 405, because the server has nothing to push between calls and an SSE stream that never speaks is worse than none. The Origin header is validated on every request.

A tool that fails answers with isError and a message explaining what to do instead — not a transport error, because the model is meant to read it and try something else.

See also: CLI · API overview · Flow schema