Flowmails MCP
by wms-why
README.md
# Flowmails MCP
The hosted [Model Context Protocol](https://modelcontextprotocol.io) server for
[Flowmails](https://flowmails.net) — a custom-domain email platform built for AI agents.
Point any MCP client at **`https://sdk.flowmails.net/mcp`** with a Flowmails bearer token,
and the agent gets a mailbox on your own domain: send mail, read the inbox, search history,
and **wait** for an inbound message instead of polling.
- **Transport:** MCP Streamable HTTP, JSON-RPC 2.0, protocol revision `2025-06-18`
- **Auth:** `Authorization: Bearer <flowmails-api-key>` (an SDK key `fm_…` or an agent credential `agc_…`)
- **Tools:** 12 (ten of them can change mailbox state; every call is scope-checked first)
- **Run it:** hosted — nothing to install, no server to operate
- **Pricing:** the platform's — Base is free, Pro $9.9/mo, Enterprise $39.9/mo. Your email
provider bills you directly; Flowmails charges no per-email markup.
---
## Why it exists
Most "email MCP servers" wrap an inbox API. This one is built around the hard part of agent
workflows: **waiting**.
`wait_for_email` opens a durable wait on an address and a subject. The platform owns that
state, so the wait survives the edge, and the agent is handed the message when it lands — it
does not spin on an inbox polling loop. That is the difference between an agent that can run a
sign-up flow unattended and one that has to be babysat.
Sending is the same contract as the REST API and the official SDK: one key, bound to one
domain, with an idempotency key and an audit trail behind every send.
## Install
### Claude Code / Claude Desktop
```bash
claude mcp add --transport http flowmails https://sdk.flowmails.net/mcp \
--header "Authorization: Bearer fm_..."
```
### Cursor / VS Code / Codex / any MCP client
```json
{
"mcpServers": {
"flowmails": {
"url": "https://sdk.flowmails.net/mcp",
"headers": {
"Authorization": "Bearer fm_..."
}
}
}
}
```
### Any client, raw JSON-RPC
```bash
curl -X POST https://sdk.flowmails.net/mcp \
-H "Authorization: Bearer fm_..." \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
## The tools
| Tool | Scope | What it does |
|---|---|---|
| `list_domains` | `addresses:read` | List the domains the credential can touch |
| `list_addresses` | `addresses:read` | List the inbound addresses of a domain |
| `create_address` | `addresses:write` | Provision a new inbound address |
| `search_emails` | `messages:search` | Search message history |
| `get_email` | `messages:read` | Read one message (body, attachments, headers) |
| `send_email` | `messages:send` | Send mail from a domain-bound address |
| `get_send_status` | `send_status:read` | Delivery status of a sent message |
| `wait_for_email` | `waits:write` | Open a durable wait on an address + subject |
| `get_wait_status` | `waits:read` | Check a wait (pending / resolved / expired) |
| `list_events` | `events:read` | Read the event log (cursor-based) |
| `claim_message` | `messages:claim` | Claim a message so a second agent won't take it |
| `complete_message` | `messages:claim` | Mark a claimed message as handled |
The scope check runs **before** the tool does, so a read-only credential cannot send, and a
credential bound to one domain cannot touch another.
## A typical agent flow
```
list_domains → create_address → wait_for_email → get_email → send_email → get_send_status
```
No dashboard visit in between. The MCP server is the protocol-level door onto the same
contract the REST API, the SDK and the CLI use.
## Links
- Landing page: <https://flowmails.net/mcp>
- Documentation: <https://flowmails.net/docs>
- For AI coding agents: <https://flowmails.net/for/ai-coding-agents>
- OpenAPI 3.1: <https://flowmails.net/openapi.json>
- SDK: [`@flowmails/flowmails-sdk`](https://www.npmjs.com/package/@flowmails/flowmails-sdk) ·
CLI: [`@flowmails/cli`](https://www.npmjs.com/package/@flowmails/cli)
## Registry metadata
This repository is the source of truth for the server's entry in the official MCP Registry:
see [`server.json`](./server.json). The name is `io.github.wms-why/flowmails-mcp`.
## License
MIT — see [LICENSE](./LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data