connect your inbox to your agent

Intro

Exposing a SQL API for email makes it incredibly powerful to run searches you will never be able to run in Gmail, Fastmail, or any other client. Most of these products trade easy-to-use search bars for expressiveness, sacrificing the ability to run complex queries and aggregations. Faist does the inverse. It prioritizes expressiveness by giving you full power and control over your email and the ability to search it however you want — to get the answers fast — and avoids trading off UX by making natural-language query a first-class citizen.

In short, you can ask "which email threads went cold after my last reply" or "which emails consume the most space" or "find similar emails to the one I got from Alice yesterday" and faist will translate them behind the scenes into a query against the email database and answer in a blink.

Getting started

To start, you need two things:

1. A Fastmail account.
2. A Supabase account.

We chose Supabase as the underlying database provider because it offers a generous free tier for trial and has an extremely easy sign-up flow — you can create an account in a few seconds and connect it to faist right after.

Open faist.mail; the onboarding wizard will take you through the rest.

Connecting to agents

Fastmail offers an MCP server of its own, but it has several shortcomings — most importantly, it doesn't expose a search interface that agents can use to find relevant information quickly. We've observed up to 10× less token usage through the combination of SQL and similarity search, because the agent can ask one precise question against an index instead of paging through a JMAP mailbox.

Two ways to authenticate

• OAuth (recommended). Paste https://faist.mail/mcp into your client — no key, no header. The client discovers faist's authorization server, opens a browser, you click approve in the faist tab, and that's it. Tokens are bound to your account, listed under CONNECTED AGENTS in the dashboard, and revocable with one click. Works in any client that follows the MCP 2025-06-18 authorization spec (Claude, ChatGPT, MCP Inspector, recent Codex, …).
• API key. Mint a faist_pat_… token from the dashboard and paste it into a Authorization: Bearer header. Use this for headless / CI clients, or any client that doesn't yet implement the OAuth dance. See API keys (headless) at the bottom of this page.

Both paths hit the same /mcp endpoint; the bearer validator branches on token prefix. You can mix them — e.g. OAuth for Claude on your laptop, an API key for a server-side job.

Claude · Cowork (claude.ai)

1. Open claude.ai and sign in.
2. Click your avatar → Settings → Connectors.
3. Add custom connector with URL https://faist.mail/mcp — leave the header field empty.
4. Save. Claude opens a faist sign-in tab — click approve.
5. Enable faist from the tool picker in any chat.

Claude Code (CLI)

claude mcp add faist --transport http https://faist.mail/mcpcopy

The first request triggers a browser tab; approve and you're signed in. Verify with claude mcp list — faist should show up with three tools (schema, sql-query, query).

claude mcp add faist --transport http https://faist.mail/mcp \
  --header "Authorization: Bearer $FAIST_KEY"copy

ChatGPT

1. Open chatgpt.com (Plus, Pro, Team, or Enterprise).
2. Settings → Beta features → Custom connectors (location varies by tier).
3. Add MCP server with URL https://faist.mail/mcp — no header.
4. Save. ChatGPT opens a faist sign-in tab — click approve.
5. Toggle the connector on in the composer.

Codex (CLI)

codex servers add faist --url https://faist.mail/mcpcopy

Recent Codex versions handle the OAuth handoff for you (browser opens automatically).

codex servers add faist --url https://faist.mail/mcp \
  --auth "Bearer $FAIST_KEY"copy

OpenClaw

openclaw add-mcp faist https://faist.mail/mcpcopy

Or hand-edit openclaw config → integrations → mcp. Browser-based OAuth is on by default for HTTPS endpoints.

openclaw add-mcp faist https://faist.mail/mcp --key $FAIST_KEYcopy

Hermes

hermes link faist --url https://faist.mail/mcpcopy

Or via the UI: Hermes → connections → add MCP. Hermes runs the OAuth flow in a popup.

hermes link faist --url https://faist.mail/mcp --key $FAIST_KEYcopy

Vanilla MCP

Any MCP-compatible client. Point it at the streamable-HTTP endpoint:

https://faist.mail/mcpcopy

Spec-compliant clients (MCP 2025-06-18) follow the WWW-Authenticate hint from a 401 response to /.well-known/oauth-protected-resource, then run dynamic client registration and the PKCE dance automatically. Smoke-test with the official inspector:

npx @modelcontextprotocol/inspector
# transport: Streamable HTTP · url: https://faist.mail/mcp
# leave Authorization blank — Inspector will prompt for sign-incopy

For clients that don't speak OAuth, send Authorization: Bearer $FAIST_KEY instead.

API keys (headless)

API keys are the escape hatch for headless / CI / non-OAuth clients. Mint them from the dashboard, in the MCP · AGENTS cell.

1. Click + new key.
2. Name it after the device or client it's for (e.g. macbook · claude).
3. Click mint. The plaintext token (faist_pat_…) appears once, in a green box. Copy it now — faist only stores the SHA-256 hash, so a lost key can be replaced but never recovered.
4. Paste it into the snippet above in place of $FAIST_KEY.

The same cell lists every active key with its name, age, and a revoke button. One key per device is a good default; revoking is instant and the agent will start failing with 401 on its next request. OAuth connections live in the CONNECTED AGENTS section right above and are revoked the same way.

Privacy

We built faist with privacy in mind:

1. The data is not stored on faist servers — every email and embedding lives in your Supabase project. Faist orchestrates polling, embedding, and indexing, but never owns the data.
2. Your embeddings are not used for training — we route through providers with zero-retention policies (OpenAI, Mistral) and never re-share batches across users.
3. Your queries are not used for training, not logged, not retained. They are yours and discarded immediately after the query completes.