MCP server

Connect your AI tools, Claude Code, Claude Desktop, Cursor, or anything else that speaks MCP, straight to your Mara workspace. Your agent can read your journeys, drafts, sends, and Playbook, and act on your behalf: draft a journey, approve a send, pause something that is not working. It runs under the same guardrails as your dashboard chat.

This page is the complete spec, written for humans and for AI coding agents. The raw markdown lives at hiremara.com/docs/mcp.md. The fastest path: open Settings, then Integrations, then MCP (AI tools) in your dashboard, generate a key, and copy the ready-made connect command.

What it is

POST /api/mcp is a remote MCP server over Streamable HTTP. Every call authenticates, resolves your workspace, runs one tool, and returns. There is no separate session to manage; each request carries your key and stands on its own.

Authentication

Auth is a per-workspace key with the prefix mara_mcp_, generated from Settings, Integrations, MCP (AI tools). The raw key is shown exactly once at generation; Mara stores only a hash. You can hold several live keys at once, one per machine or agent, and revoke any of them without touching the others.

Send it as a bearer token:

Authorization: Bearer mara_mcp_...

This is a credential for your own tools, not a public API. Keep it out of source control the same way you would an API key for any other service.

Connect Claude Code

claude mcp add --transport http mara https://hiremara.com/api/mcp --header "Authorization: Bearer <your-mcp-key>"

Run it once from anywhere; Claude Code remembers the connection. Your settings row's copy button fills in your real key.

Connect Claude Desktop

Add an entry to your MCP config (Settings, Developer, Edit Config in Claude Desktop):

{
  "mcpServers": {
    "mara": {
      "url": "https://hiremara.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-mcp-key>"
      }
    }
  }
}

Restart Claude Desktop after saving.

Connect Cursor

Cursor reads the same shape. Add it under Settings, MCP:

{
  "mcpServers": {
    "mara": {
      "url": "https://hiremara.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-mcp-key>"
      }
    }
  }
}

The approval promise

Nothing sends to a customer without approval in your dashboard queue, unless your own policy gate says otherwise (for example, a reply-autonomy setting you turned on yourself). Drafting tools call a model and can take up to a minute or so to return; everything else is a fast read or a direct database action. A drafted email lands pending_approval exactly the same way it would from chat: you approve it, or Mara's autonomy setting does, never the tool call by itself.

Connect your product

If you self host, or you have no CRM connected, the fastest way in is to hand your coding agent one instruction: set up the Events API for me. Two tools close the loop end to end, in one conversation, without you ever opening Settings:

1. setup_events_ingestion mints your ingestion key (or reports its status if one already exists), hands your agent the exact endpoint URL, and optionally maps which event means "a new user signed up."
2. Your agent writes the integration, using the linked spec at /docs/events-api.
3. check_recent_events confirms the test event your agent fires actually landed, with a per-connector health summary, so you get a "done, verified" report instead of a "should be working" guess.

Both tools are MCP-only: they never appear in your dashboard Chat pane, since chat is not the place for a raw ingestion key to surface.

Tools

Eight tools only ever read:

Nineteen tools act, each holding to the same approval promise above:

configure_journey_spine shapes the state spine container only, the funnel stages themselves, not what any event means. Confirming or rejecting what an event means used to be a founder-only decision on the Journeys page. It no longer is: set_event_mapping lets your agent make that call directly, on your explicit instruction, the same trust model as approve_journey or pause_journey. It appends to the same append-only mapping log the Journeys page confirm UI writes to, so the latest decision always wins, and nothing is ever silently edited or removed.

One tool is Mara herself:

Two tools set up and verify your own product's event integration. They are MCP-only: they never appear in your dashboard Chat pane, since a raw ingestion key has no business surfacing there.

Rate limits

The endpoint allows 60 calls per minute per key. ask_mara is stricter on top of that: 10 calls per minute per key, and 200 per day per workspace, since each call is a real model turn rather than a cheap read. Over a limit you get a clean tool error naming the wait, not a broken connection.

Verify it landed

Ask your agent to call list_active_journeys or list_pending_drafts first. A working connection returns your real workspace data immediately; a wrong or revoked key returns an authorization error before anything else runs.

For AI coding agents

If you are an agent setting this up for a founder, the checklist:

1. Tell the founder to generate a key from Settings, Integrations, MCP (AI tools), and copy it into your config or the connect command. Never ask for it in plain chat if a copy button is available.
2. Register the server with the client the founder is using (Claude Code, Claude Desktop, Cursor) using the blocks above.
3. Confirm the connection with a read-only call (list_active_journeys is a good first check).
4. If the founder self hosts or has no CRM connected, call setup_events_ingestion to mint their key and get the exact endpoint URL, write the integration against /docs/events-api, then call check_recent_events after firing a test event to confirm it landed. Never mint a second key with rotate: true on a routine check; that revokes the founder's live key.
5. Remember every action tool still lands pending_approval in the dashboard, or waits on the founder's own autonomy setting. Do not tell the founder something "sent" because a tool call returned; check list_sent or the dashboard for the real outcome.
6. Treat every key like any other credential: one per machine, revoked the moment a machine is retired.