Mankomail

MCP server ​

The Model Context Protocol (MCP) lets an AI assistant call tools offered by another application. Every Mankomail instance exposes an MCP server: Claude Desktop, Claude Code, Cursor or any MCP client can connect to it and work on your workflows and mailboxes, with your permissions and nothing more.

The server publishes the tools layer of the instance, the same typed tools that the analyzer and the workflow assistant use internally. What an assistant sees through MCP is exactly what Mankomail itself works with.

What an assistant can do ​

Each tool is one capability of the instance, with a name, a description, a typed input and a typed output. Tools are grouped by domain:

  • Catalog and documentation: list the nodes you may use, describe one node in full (parameters, output ports, data it produces, connections it needs), search and read this documentation.
  • Workflows: list your workflows, read one in full with its validation and history, validate or compile a proposal, propose a new workflow or changes to an existing one, run the draft on a real email as a test run, then create a draft, update a draft and publish.
  • Executions: list recent runs, read one step by step to see what each node produced and where it failed.
  • Mailboxes: list your mailboxes, get their statistics, group recent emails into flows, search by sender or subject (headers and previews, never a full body), list what no workflow handled, and simulate which emails your published workflows would have taken.
  • Connections: which connections nodes can require and whether each is configured for you.
  • Tables: list the Tables with their columns, and create one.

The full list, with inputs and outputs, is in Tools reference.

The trust model ​

An MCP client authenticates with an API key, created in Settings › API keys. A key acts on behalf of the member who created it, with that member's role, mailboxes and scope, and is further limited by the scopes chosen when it was created. A scope never adds a right: it only removes some.

  • Read and write are separate. Each tool is either a read tool or a write tool. A read tool needs the read scope of its domain, a write tool the write scope. The four write tools are workflow_create_draft, workflow_update_draft, workflow_publish and tables_create.
  • Nothing is published without workflows:write. A key with workflows:read lets an assistant explore, propose and compile (testing takes executions:write), but every proposal stays a value in the conversation: the member creates the draft or publishes it, in the editor or with a key that holds workflows:write.
  • The assistant only sees what it may call. tools/list returns the tools allowed by the key's scopes; a call to any other tool is refused with a named error. See Scopes and tools.
  • No secret is ever exposed. connections_list says whether a connection is configured and names the usable credentials; it never returns a token, a password or an API key. Email bodies are never returned either: mailbox tools work on headers and bounded previews.
  • A table is created by administrators only, as in the interface: the key of an ordinary member cannot create one even with tables:write.

A test run needs executions:write, like the REST route that runs one. It sends and writes nothing outside the instance, but AI nodes do call their model (which costs money), and it is recorded as a simulated execution.

The endpoint ​

The server answers at POST <PUBLIC_BASE_URL>/api/v1/mcp with the Streamable HTTP transport of the current MCP specification. Send the key in the Authorization header:

http
POST /api/v1/mcp HTTP/1.1
Authorization: Bearer mk_…
Content-Type: application/json
Accept: application/json, text/event-stream

The transport is stateless: each request carries its key, builds the server for that key's member, and nothing survives between two calls. The server assigns no session id, so there is no Mcp-Session-Id header to send back, and a revoked key is refused from the very next request. Consequences:

  • GET and DELETE on the endpoint return 405 Method Not Allowed: there is no server-initiated stream and no session to end. No tool needs either.
  • Responses are plain JSON when the client does not require an SSE stream, which keeps curl and minimal clients simple.
  • Several replicas of the server serve the same client without coordination.

A browser session also authenticates the endpoint: a signed-in member reaches every tool their role allows. The MCP server is distinct from the REST API, which exposes the same resources as HTTP routes; both accept the same keys, see Authentication.

Where to go next ​

  • Connect a client: Claude Desktop, Claude Code, Cursor, and a raw curl session.
  • Tools reference: every tool with its inputs and what it returns.
  • Scopes and tools: which scope each tool needs, how refusals look, and example key configurations.