## 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**](https://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](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) (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)**](#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**](https://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.

<details><summary>Or use an API key (no browser)</summary>

Use the same flow, but in step 3 set `Authorization: Bearer $FAIST_KEY` as a custom header instead of leaving it blank. Mint the key first — see [**API keys (headless)**](#api-keys-headless).

</details>

### Claude Code (CLI)

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

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`).

<details><summary>Or use an API key</summary>

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

</details>

### ChatGPT

1. Open [**chatgpt.com**](https://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.

<details><summary>Or use an API key</summary>

In step 3, add header `Authorization: Bearer $FAIST_KEY`.

</details>

### Codex (CLI)

```bash
codex servers add faist --url https://faist.mail/mcp
```

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

<details><summary>Or use an API key (older Codex)</summary>

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

</details>

### OpenClaw

```bash
openclaw add-mcp faist https://faist.mail/mcp
```

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

<details><summary>Or use an API key</summary>

```bash
openclaw add-mcp faist https://faist.mail/mcp --key $FAIST_KEY
```

</details>

### Hermes

```bash
hermes link faist --url https://faist.mail/mcp
```

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

<details><summary>Or use an API key</summary>

```bash
hermes link faist --url https://faist.mail/mcp --key $FAIST_KEY
```

</details>

### Vanilla MCP

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

```
https://faist.mail/mcp
```

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:

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

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**](https://faist.mail/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.