MCP server

Every inbox you own, exposed to your agent.

SwarmMarshal ships a Model Context Protocol server that runs on the same machine as the app. Wire it into Claude Code, Codex, or any MCP-compatible client and your agent can read, search, compose, and act across every connected account — Gmail, Microsoft Graph, IMAP — under one unified knowledge graph with source-grounded context.

Download SwarmMarshal Wire it up

What it is

One MCP. Every provider. Source-grounded.

Claude Code and Codex each ship a Gmail connector — one account, no shared context across providers. SwarmMarshal sits above that: a single MCP exposing every account you own with thread context, person history, commitments, and grounded facts already extracted.

stdio transport, runs locally

The server is SwarmMarshal.McpServer, a small .NET process speaking MCP over stdio. Logging goes to stderr; JSON-RPC owns stdin/stdout. No HTTP endpoint to harden. No remote service to trust.

Reads the same data the app reads

Points at the SwarmMarshal data directory (env var SwarmMarshal_DATA_DIR if you want to override). Per-account SQLite databases, knowledge-claim store, context-fact projections — the MCP server is a read & write surface over the same files the desktop app uses.

Tools, not endpoints

~40 typed MCP tools, organized by capability. Read tools are marked ReadOnly so agents that respect MCP semantics can run them without confirmation. Mutations land in a durable outbox and replicate to the provider on the next sync.

Tool catalog

What your agent can actually do.

The catalog is grouped by intent. Tools return JSON strings the model can consume directly; most read tools accept account scoping when you need it and span every account when you don't.

Context — the flagship

Tool	What it returns
`get_context_pack`	Query → source-grounded facts with confidence scores, citations, and a redaction level chosen by the caller (Internal, PeerShareable, ExternalTool).
`get_thread_context`	Thread → participants, action items, commitments, and a last-N message rollup. The thread is JWZ-stitched across References / In-Reply-To, not just subject-matched.
`get_person_context`	Person → relationship history across every connected account at once. Common topics, last interaction, response patterns.
`get_company_context`	Company / domain → who you talk to there, what about, and what's currently in flight.

Search & read

Tool	What it returns
`search_messages`	Full-text search across every account in one call. Returns matches with thread, account, and source-ref.
`search_messages_semantic`	Vector search over enriched message embeddings. Use when the caller doesn't remember the words.
`find_related_messages`	Given a message, find its semantic neighbors. Good for "what else like this?" follow-ups.
`search_entities · search_contacts · search_contacts_semantic`	Knowledge-graph entity lookup. People, companies, projects — extracted from real communication, not a directory import.
`list_recent_messages · get_message · get_thread · list_accounts · unread_count`	The everyday read primitives. Account-scoped where it matters; cross-account where it helps.

Act on the inbox

Tool	What it does
`send_message · reply_to_email · forward_email · save_draft`	Compose and send across the right provider. Native Gmail / Microsoft Graph paths used when available; SMTP only as the floor.
`mark_message_read · flag_message · delete_message · move_message · snooze_message`	Mutations are durable. They land in the outbox first and replicate to the provider on the next sync — surviving crashes, restarts, and offline windows.
`list_folders · list_rules · create_rule · toggle_rule · delete_rule`	Inspect and shape the inbox policy the agent will see. Rules are user-authored plain English.

SwarmMarshal agent operations

Tool	What it does
`list_agent_profiles · apply_agent_role · request_agent_cycle`	Inspect SwarmMarshal's internal agent profiles, swap roles, request a cycle. Useful when you're orchestrating SwarmMarshal from a larger agent system.
`get_recent_journal · list_agent_proposals`	Read what SwarmMarshal's own agents have been doing and what they want to propose. Audit trail in, audit trail out.

Wire it up

Three configs you'll write once.

SwarmMarshal installs the MCP server binary alongside the app. Point your MCP-aware client at it via its config file.

Claude Code

Add an entry to your Claude Code MCP config (typically ~/.config/claude/mcp.json or the equivalent on your platform):

{
  "mcpServers": {
    "swarmmarshal": {
      "command": "SwarmMarshal.McpServer",
      "args": [],
      "env": {
        "SwarmMarshal_DATA_DIR": "C:/Users/you/Documents/SwarmMarshal/default"
      }
    }
  }
}

Codex CLI

Codex reads MCP servers from its config:

{
  "mcp": {
    "servers": {
      "swarmmarshal": {
        "command": "SwarmMarshal.McpServer"
      }
    }
  }
}

Any MCP-aware client

The transport is plain MCP stdio; any client that speaks the protocol can launch the binary. The server identifies itself as SwarmMarshal v1.0.0 on handshake and advertises the full tool catalog from WithToolsFromAssembly().

Redaction levels

One server. Three audiences. Three views.

Context tools take a redaction level so the same query returns the right amount of data for the right caller. The trust boundary is encoded in the context pack itself, not negotiated out-of-band.

`Internal`

For SwarmMarshal's own agents running on your machine. Sees everything: durable memories, knowledge claims, life facts, contacts, and message bodies.

`PeerShareable`

For trusted peer replicas — your other devices running SwarmMarshal in peer-to-peer mode. Wider than ExternalTool but excludes the most sensitive personal facts unless explicitly opted in.

`ExternalTool`

For agents and MCP clients outside SwarmMarshal's trust circle. PII stripped, internal identifiers redacted, only fields you've approved for external use are returned. This is the default for unfamiliar clients.

Trust model

The data layer enforces what the prompt can't.

An MCP server is only as safe as what flows back through it. SwarmMarshal's data-layer guards are the reason exposing inboxes to a remote agent isn't a footgun.

Knowledge promotion is gated A single inbound message can create a KnowledgeClaim but never a durable UserMemory. Promotion requires user-authored, trusted-contact, or corroborated status. Agent queries that read UserMemory can't be poisoned by a single hostile email.
Sources travel with facts Every durable record carries a SourceRef — kind, account ID, record ID, excerpt, observed-at. An agent that returns a fact can always be asked to surface the message. No hidden provenance.
Deletion cascades or tombstones Delete a message and registered IMessageDeletionObserver implementations dispatch cleanup. Derived data either disappears or tombstones with a recorded source-was-deleted reason. Stale data doesn't accumulate.
Suppression survives reset If you reject a claim, a KnowledgeSuppression row blocks the system from relearning it from a future message. The agent can't talk you back into it by quoting a duplicate.
Routing respects privacy classes LLM calls SwarmMarshal makes on the agent's behalf go through ILlmRouter. Set PrivacyClass = LocalOnly on sensitive function types and prompts never leave the machine — enforced before any cost / quality advisor runs.

Plug it in

Download SwarmMarshal, connect your accounts, point your agent at the MCP.

Your agent now reads, queries, and acts across every inbox you own — with citations, redaction, and a memory layer that won't quietly drift.

Download Architecture deep dive