# fmsg-mcp

[![Tests](https://github.com/markmnl/fmsg-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/markmnl/fmsg-mcp/actions/workflows/tests.yml)
[![npm](https://img.shields.io/npm/v/%40markmnl%2Ffmsg-mcp)](https://www.npmjs.com/package/@markmnl/fmsg-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

An [MCP](https://modelcontextprotocol.io) server that gives any AI agent its own
[fmsg](https://github.com/markmnl/fmsg) address: send messages, follow threads, react, exchange
attachments and wait for replies, through a deployed
[fmsg Web API](https://github.com/markmnl/fmsg-webapi). Connect through stdio in hosts such as
Claude Code, Claude Desktop, Cursor and VS Code, or through HTTP using API-key headers or configured OAuth.

Use your choice of fmsg hosting provider, or self-host. No hosting provider or identity provider
is built in.

- **stdio** for local hosts: one address per server process, configured by two environment variables.
- **Streamable HTTP** for shared or remote deployments: one endpoint serving many users, each
  authenticated by their own fmsg API key or OAuth connection.
- The fmsg Web API client is exported for reuse: `import { FmsgClient } from "@markmnl/fmsg-mcp/client"`.

## 1. Choose a connection

### OAuth: connect and sign in

Get an OAuth-enabled MCP URL from your fmsg hosting provider, add it to your AI host, and sign in.
You do not need an API key or a local installation for this connection. Your AI host must support
the authorization server's client registration method; see [OAuth onboarding](docs/oauth.md#discovery-and-client-onboarding).
Operators can enable this with [HTTP OAuth](docs/oauth.md).

### API key: use locally or over HTTP

You send as an fmsg address, authenticated by an API key (`fmsgk_…`) issued by your fmsg host:

- **Using a hosting provider?** Create an account with an fmsg hosting provider and obtain an
  API URL and API key for the address your agent will use.
- **Self-hosting?** Run the stack with [fmsg-docker](https://github.com/markmnl/fmsg-docker) and issue
  a key with `fmsg-webapi api-key create`.

Use the API URL and key for local installation below, or use your provider's API-key MCP endpoint
with an `Authorization: Bearer fmsgk_...` header. The endpoint must use the fmsg Web API that accepts
your key.

An agent's key is usually for a **sub-address** such as `@user_agent@example.com`, owned by
`@user@example.com`. The owner can switch to the sub-address in their client, but can only follow
and reply to threads they are a participant of. So `send_message`, `reply` and `create_draft` add the
owner as a recipient unless `include_owner` is false; `whoami` reports the owner.

### MCP Registry

Find `io.github.markmnl/fmsg-mcp` in the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.markmnl%2Ffmsg-mcp).
The listing offers local npm installation and configurable remote connections for OAuth or API keys.
For a remote connection, supply the MCP endpoint from your fmsg hosting provider or your own deployment;
the registry input takes its hostname and path without the `https://` prefix, such as `mcp.example.com/mcp`.
OAuth sign-in is discovered from that endpoint; the API-key option additionally asks for your key.
If your AI host cannot configure registry URL templates, add the full MCP URL directly instead.

## 2. Install

Requires Node.js 22 or later.

### Claude Code

```sh
claude mcp add fmsg --scope user \
  --env FMSG_API_URL=https://api.example.com \
  --env FMSG_API_KEY=fmsgk_... \
  -- npx -y @markmnl/fmsg-mcp
```

Then in any session: *"Send @bob@example.com a note about the release"*, *"What's in my fmsg inbox?"*,
*"Wait for Bob's reply and answer it"*. `/fmsg:chat`, `/fmsg:reply` and `/fmsg:send_file` are available as prompts.

### Claude Desktop, Cursor, VS Code and other stdio hosts

Add a server entry with the same command; only the config file differs:

```json
{
  "mcpServers": {
    "fmsg": {
      "command": "npx",
      "args": ["-y", "@markmnl/fmsg-mcp"],
      "env": { "FMSG_API_URL": "https://api.example.com", "FMSG_API_KEY": "fmsgk_..." }
    }
  }
}
```

(Claude Desktop: `claude_desktop_config.json`; Cursor: `.cursor/mcp.json`; VS Code: `.vscode/mcp.json`
under `"servers"` with `"type": "stdio"`.)

### Remote (Streamable HTTP) mode

Run one server for many users. Each client sends **its own** fmsg API key as a bearer token; the
server exchanges it at the fmsg host and acts as that address. `FMSG_API_KEY` must not be set.

```sh
FMSG_API_URL=https://api.example.com FMSG_MCP_ALLOWED_HOSTS=mcp.example.com \
  npx -y @markmnl/fmsg-mcp --http 0.0.0.0:8765
# or
docker build -t fmsg-mcp --build-arg FMSG_MCP_COMMIT=$(git rev-parse HEAD) \
  --build-arg FMSG_MCP_VERSION=$(git describe --tags --abbrev=0) .
docker run -e FMSG_API_URL=https://api.example.com \
  -e FMSG_MCP_ALLOWED_HOSTS=mcp.example.com -p 8765:8765 fmsg-mcp
```

The MCP endpoint is `/mcp`; `/healthz` reports liveness, the version and the commit. `whoami` reports the
same, so a client can confirm which deploy it is talking to: `npm run build` records them from git, and the
Docker build arguments above do so where the build has no git history (`FMSG_MCP_COMMIT` can also be set at
run time). Use a client that supports an explicitly
configured `Authorization: Bearer fmsgk_...` header. Each caller supplies its own key; a shared
header means a shared fmsg identity. For browser sign-in without user API keys, configure
[HTTP OAuth](docs/oauth.md): the operator supplies an issuer, resource URI and exchange client.
Users add the public MCP URL in a host supporting that issuer's client registration method.
`FMSG_MCP_AUTH_MODE=oauth+api-key` accepts both OAuth and API-key callers on the same URL.

For [Claude Code over HTTP](https://code.claude.com/docs/en/mcp):

```sh
claude mcp add --transport http fmsg --scope user https://mcp.example.com/mcp \
  --header "Authorization: Bearer fmsgk_..."
```

Deploy behind a TLS-terminating reverse proxy and set `FMSG_MCP_ALLOWED_HOSTS` to the public hostname
when binding to a non-loopback address; startup fails without it. Browser clients on another origin
also need `FMSG_MCP_ALLOWED_ORIGINS` containing exact origins, such as `https://app.example.com`.
For loopback binds, loopback browser origins on any port work by default, including MCP Inspector
at `http://localhost:6274`. Setting an explicit origin list replaces that loopback default.
Allowed preflights need no credentials; actual MCP requests always require authentication.
`wait_for_message` holds a request open for up to
`FMSG_MCP_WAIT_MAX_SECONDS` (230), so give the proxy an idle timeout of at least 240 s. On SIGTERM
the server ends open waits with an `interrupted` result that clients resume from, gives other
requests 5 seconds to finish, and exits, well within a service manager's stop timeout.
See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback deployment with Caddy.

## Tools

| Tool | What it does |
|---|---|
| `whoami` | The address this server acts as, its `owner` if it is a sub-address, the public API URL (when known), the transport (`stdio` or `http`, which is Streamable HTTP), short-name defaults, and this server's version and commit |
| `resolve_address` | Turn a short name into `@user@domain` (directory, then default domain) |
| `list_messages` | Inbox, newest first, with previews, attachment types and `size` (`compressed` marks a body sent deflated); reactions hidden and never counted as unread unless `include_reactions` |
| `list_sent` | Sent messages with per-recipient delivery state |
| `get_message` | One message with headers, full text body, attachments, reactions and, for a reply, the root's `thread_topic` |
| `get_thread` | The lineage from the thread root to a message (`scope: "lineage"`; other replies in the thread are not included), with gaps for messages you cannot see, per-message flags and added recipients, the root's `thread_topic`, and a `next` step that never suggests replying to a terminal or no-reply message |
| `send_message` | Start a new thread; sends immediately (fmsg messages are immutable) |
| `reply` | Reply into a thread; reply-all by default, refuses terminal and no-reply parents |
| `create_draft` | Create an unsent message or reply (`reply_to`) that other fmsg clients can see; over HTTP with a public MCP URL, returns an authenticated upload URL for large attachments |
| `send_draft` | Send a draft, with its attachments |
| `delete_draft` | Discard an unsent draft |
| `add_recipients` | Add `recipients` to a sent message (`add_to` is a deprecated alias) |
| `react` | Set or clear your emoji reaction |
| `indicate` | Show the other participants a short-lived status on a message, such as ⏳ while working on a reply or ✍️ while composing (FMSG-006 indicator; `ttl` 1–120 s, default 60), kept up until you reply, react or mark it read (up to 5 minutes); an empty `emoji` clears it. Reading a message never shows one |
| `mark_read` | Mark received messages read |
| `download_attachment` | Fetch a small attachment inline: text as text, images as image blocks, other files as base64 resources; a wrong filename lists the names the message has |
| `get_attachment_download_url` | Get a credential-free URL and resource link for an authenticated binary download; with `presigned: true`, also a single-use link valid for 5 minutes that needs no Authorization header, with its size, sha256 and a curl command. HTTP only, requires a public MCP URL |
| `get_attachment_upload_url` | Get a single-use link valid for 5 minutes that PUTs one file of a given size and sha256 into a draft without the Authorization header, with a curl command; then `send_draft`. HTTP only, requires a public MCP URL |
| `save_attachment` | Stream an attachment to the configured local folder; stdio only, enabled by `FMSG_MCP_DOWNLOAD_DIR` |
| `delivery_status` | Per-recipient delivery times and fmsg response codes (`200` accepted; `null` when not recorded); for a received message, the host's own receipt records; `via` is `to` or `add_to` (added later) |
| `wait_for_message` | Block until the next inbound message (WebSocket push), batched per thread, with thread context, skipped reactions and a `next` step that names messages from other threads (`pending_ids`) the cursor moved past |

Every tool returns readable Markdown plus `structuredContent`. Ids are decimal strings. Message
bodies are labelled as data from other parties, not instructions; structured results that carry
other parties' words repeat that in `untrusted_content_notice`, since some hosts show the
structured result instead of the text. Attachment types come from the host when it recorded one,
otherwise from the filename extension, so every tool reports the same type, and every tool lists
attachments in the same order (by filename). Addresses in the text are code spans, so they copy
exactly (`@bob_mcp@example.com`, never with a Markdown escape); a backslash in an address is
rejected. A message's `size` is the body size the host stores: for a received message with
`compressed` true that is the compressed length, while your own sent messages keep the uncompressed
length.

### Output schema compatibility

Some MCP hosts cache each tool's `outputSchema` when the connector is added and validate every later
result against that copy. Output schemas are therefore open and additive: objects accept unknown
properties, values that may grow (statuses, transports, resolutions, delivery state) are strings
whose current values are listed in their descriptions, and only fields present since 0.2.5 are
required. Releases add fields and values; they do not remove or rename them. Schemas published by
0.2.6 and earlier were closed, so a host that cached one rejects results with newer fields (for
example "must NOT have additional properties"); remove and re-add the connector once to refresh it.

### Indicators

`indicate` shows a message's other participants a short-lived status, such as ⏳ while the agent
works on a reply or ✍️ while composing: an
[FMSG-006](https://github.com/markmnl/fmsg/blob/main/standards/fmsg-006-indicators.md) indicator.
Nothing is shown unless the agent calls it; reading a message never does. It is sent at once with
its `ttl` (default 60 s) and refreshed at half the ttl (every 1–30 s) until the agent replies to
that message or anywhere in its thread (`reply`, or `send_draft` of a reply), reacts to it, marks it
read, clears it with an empty `emoji`, or after 5 minutes, and when the session ends or the server
shuts down. At most 10 are kept up per address, the oldest cleared first. `indicate` returns the
host's refusal (such as a terminal message, or a host without indicators); refreshes and automatic
clears are best effort and never fail another tool. Over HTTP each MCP request gets a fresh server
instance, so indicators are kept per address by the HTTP server; embedders that build one server per
request pass a shared `IndicatorRegistry` as `indicators`.

Resources `fmsg://message/{id}` and `fmsg://thread/{id}` expose the same content to hosts that
attach resources; prompts `chat` and `reply` script the wait → reply loop and a guided reply, and
`send_file` sends files by the most efficient route the server offers.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `FMSG_API_URL` | — | Base URL of the fmsg Web API (required) |
| `FMSG_API_KEY` | — | `fmsgk_…` key; stdio mode only |
| `FMSG_API_PUBLIC_URL` | `FMSG_API_URL` (HTTP mode: only if HTTPS) | Web API URL reported to users by `whoami`; never used for requests. Set it when the server reaches the Web API at an internal address. Without it, HTTP mode reports no URL for a cleartext `FMSG_API_URL`. Validated like `FMSG_API_URL` |
| `FMSG_MCP_AUTH_MODE` | `api-key` | HTTP authentication: `api-key`, `oauth`, or `oauth+api-key` to accept both on one endpoint; see [OAuth settings](docs/oauth.md#operator-configuration) and [combined mode](docs/oauth.md#combined-oauth-and-api-key-mode) |
| `FMSG_MCP_PUBLIC_URL` | OAuth resource URL, otherwise unset | Public MCP endpoint, including `/mcp`; enables the HTTP download-link tool and draft upload URLs. HTTPS required except loopback; when OAuth is enabled must equal `FMSG_MCP_OAUTH_RESOURCE_URL` |
| `FMSG_ALLOW_INSECURE_HTTP` | disabled | Set to `1` only to permit cleartext API access on a trusted development/private network; loopback HTTP is allowed by default |
| `FMSG_DEFAULT_DOMAIN` | — | Lets short names resolve: `bob` → `@bob@<domain>`. `caller` resolves them on the domain of the address the server acts as for each request, so `@mark@example.org` gets `@bob@example.org`; directory entries still take precedence |
| `FMSG_DIRECTORY` | — | JSON file mapping short names to full addresses |
| `FMSG_MCP_DOWNLOAD_DIR` | — | Enable `save_attachment` in stdio; folder for new files named from message ID and filename |
| `FMSG_MCP_UPLOAD_DIR` | — | Allow attachment `path` arguments in stdio: files in this folder (or below it) are read by the server instead of written out by the model |
| `FMSG_MCP_WAIT_MAX_SECONDS` | `230` | Cap on one `wait_for_message` call |
| `FMSG_MCP_FILE_HOSTS` | any public host | Comma list of host names (or parent domains) that [files given by reference](#files-given-by-reference) may be downloaded from |
| `FMSG_MCP_MAX_FILE_BYTES` | `20971520` (20 MiB) | Size limit for one file given by reference |
| `FMSG_MCP_STATE_SECRET` | per-process random | At least 32 bytes; HMAC key for presigned links. Links still work only on the instance that issued them |
| `FMSG_MCP_HOST` / `FMSG_MCP_PORT` | `127.0.0.1` / `8765` | HTTP bind address (or `--http host:port`) |
| `FMSG_MCP_ALLOWED_HOSTS` | loopback names | Comma-separated `Host` header allowlist; required for non-loopback binds |
| `FMSG_MCP_ALLOWED_ORIGINS` | same origin; loopback origins on loopback binds | Comma-separated browser origins including scheme and port; an explicit list replaces the loopback default; hostname-only values are rejected |
| `FMSG_MCP_KEY_CACHE_MAX` / `FMSG_MCP_KEY_CACHE_TTL_SECONDS` | `500` / `1800` | HTTP client cache bound; TTL applies only to API-key callers |

The API key is exchanged for a short-lived access token that the server renews automatically.
API URLs must not contain credentials, query strings or fragments. Authenticated requests do not
follow redirects; configure the final API URL directly.

To save attachments directly to disk, add `FMSG_MCP_DOWNLOAD_DIR` to your stdio server's environment,
for example `/home/you/Downloads/fmsg`. The optional `save_attachment` tool streams files into that
folder without sending their bytes through model context. It accepts only a message ID and attachment
filename and creates a new file such as `123-report.pdf`. Repeat saves use `123-report-1.pdf`,
`123-report-2.pdf`, etc., leaving existing files untouched. Unusual filenames are converted to
portable names; use the returned `saved_to` path. Streaming downloads can run longer than 60 seconds
while making progress; a 60-second idle timeout detects stalled transfers.

Inline downloads default to 256 KiB to keep file content manageable for the model. Use
`save_attachment` for larger local files (stdio), `get_attachment_download_url` for remote ones
(HTTP), or raise `max_inline_bytes` explicitly when your AI host can handle more inline content.
Tool descriptions name only the tools the running server registered.

For remote file downloads, call `get_attachment_download_url` with the message ID and filename.
It returns metadata and an HTTPS `resource_link`; your AI host downloads the original bytes using
the existing MCP connection's Authorization header. API-key operators enable the tool with
`FMSG_MCP_PUBLIC_URL=https://mcp.example.com/mcp`; OAuth deployments reuse their configured resource
URL automatically. See [Binary attachment downloads](docs/http-deployment.md#binary-attachment-downloads).
Links contain no credentials and grant no access by themselves. The host must support authenticated
HTTP downloads; an ordinary browser click without the header returns 401. Use inline downloads when
that host capability is unavailable. Downloads stream without the inline size budget, using the
original Content-Type and download filename. No files are stored on the MCP server.

### Sending attachments

`send_message`, `reply` and `create_draft` take each attachment as exactly one of:

- `data_base64`: base64 written by the model. It passes through the model, so it is best effort: fine
  for small files (verified exact up to 16 KB). Always pass `sha256` with it, and prefer `path` or a
  presigned upload link for anything larger. The standard or URL-safe
  alphabet is accepted, but not both in one value. Decoding is strict: any other character, a bad
  length or padding, or a stray ending is refused with the attachment's name, rather than sent as a
  corrupted file.
- `data_text`: text, sent as its UTF-8 bytes; no base64 overhead.
- `path` (stdio with `FMSG_MCP_UPLOAD_DIR`): a file in that folder, streamed by the server. Paths
  are relative to the folder, and a path or symlink that leads outside it is refused.

Add `sha256` (hex) to any attachment and the server checks the bytes against it; a mismatch is
refused before anything is sent. For large files over HTTP, call `create_draft`, PUT the files to
the returned upload URL with the connection's Authorization header (optionally gzip-compressed and
with `x-content-sha256`), then `send_draft`; see
[attachment uploads](docs/http-deployment.md#attachment-uploads). Send files as they are: fmsg
compresses message bodies and attachments itself when it sends them.

#### Files given by reference

`send_message`, `reply` and `create_draft` also take `files`: files the user shared in the chat,
which the host fills in and the server downloads itself. This is ChatGPT's
[`openai/fileParams`](https://developers.openai.com/apps-sdk/reference): each of the three tools
declares `_meta["openai/fileParams"]: ["files"]`, and ChatGPT passes each file as
`{ download_url, file_id, mime_type?, file_name? }`. The bytes never pass through the model, and the
model needs no HTTP access of its own (ChatGPT's sandbox has none). Other hosts ignore the field.

- Only `https` URLs, with no credentials in them, and at most 3 redirects. Every hop must resolve to a
  public address: loopback, private, link-local (including cloud metadata), CGNAT, multicast and
  reserved addresses are refused, and the connection goes to the address that was checked.
  `FMSG_MCP_FILE_HOSTS` narrows the allowed hosts further.
- Each file is limited to `FMSG_MCP_MAX_FILE_BYTES` and 30 seconds.
- The name is the host's `file_name` made safe (letters, digits, dot, underscore, hyphen; `file.<ext>`
  from the type when there is none), renamed `name-2.ext` on a clash.
- The bytes are hashed as they download. The upload is checked against that sha256, and the result's
  `files` lists each file's `file_id`, name, size and `sha256`.
- Every file is downloaded before a draft is created, so one that fails leaves nothing behind.

Hosts that cannot attach the connection's credentials to their own HTTP requests can still keep file
bytes out of the model. `get_attachment_upload_url` returns a single-use, 5-minute link per draft
file, bound to its size and sha256, with a ready-to-run `curl` command. `get_attachment_download_url`
with `presigned: true` does the same for downloads. The link itself authorizes that one transfer. It
holds no API key or access token, but treat it as a secret until it is used or expires. It works only
on the server instance that issued it.

Models learn the routes from the server instructions and tool descriptions, which name only the
routes the running server offers. A model that writes a large file as base64 although a better
route exists gets a `hint` in the result naming it. The `send_file` prompt walks through the best
route. The upload URL needs a host that can send the MCP connection's credentials with its own
HTTP requests: scripts, SDK clients, and coding agents given an fmsg API key. Chat hosts usually
cannot; ChatGPT uses `files`, and for others `data_text` and `data_base64` remain the routes.

The Web API already transfers attachments as raw bytes. Base64 is used only when embedding binary
content in MCP's JSON results, as required by [MCP binary resources](https://modelcontextprotocol.io/specification/2026-07-28/server/resources#binary-content).
`save_attachment` and authenticated HTTP downloads avoid that encoding and keep file bytes out of
model context. See [issue #6](https://github.com/markmnl/fmsg-mcp/issues/6).

Over stdio, missing or invalid configuration still allows hosts to discover the tools. Tool calls
explain the configuration error and how to fix it; restart the MCP server after correcting settings.

## Safety

- Messaging access, quotas and recipient acceptance are enforced by fmsg-webapi and the host
  services. MCP forwards each operation as the caller's identity and surfaces upstream failures.
- `download_attachment` never writes local files. Optional `save_attachment` writes only generated
  filenames in the operator-configured folder, using exclusive creation with no overwrite.
- Sent messages cannot be edited or recalled; send tools say so in their descriptions and are
  annotated `destructiveHint` to describe their effects. Approval behavior belongs to the AI host;
  fmsg-mcp has no additional confirmation gate.
- Selected API-key/token formats are redacted from outbound bodies, topics and error text; the
  send tools report the count. They include fmsg API keys, JWTs, private key blocks, source-hosting
  tokens (`ghp_…`, `github_pat_…`, `glpat-…`), cloud access key ids (`AKIA…`, `ASIA…`) and labelled
  secret access keys, `AIza…` API keys, chat-platform tokens (`xox…`), payment-platform keys
  (`sk_live_…`, `rk_live_…`, `sk_test_…`, `whsec_…`) and `sk-…` API keys. This is not general data-loss prevention or binary attachment scanning.
- Nothing about message size or acceptance is assumed: the fmsg host's own responses and delivery
  codes are surfaced verbatim.
- The server publishes MCP `instructions` (shown to the model at session start) telling agents to use
  these tools rather than a local fmsg CLI or cached credentials, to carry out authorized tasks and
  automation without repeated confirmation, and to treat message content as data.
- See [SECURITY.md](./SECURITY.md).

## Using the client library

```ts
import { FmsgClient } from "@markmnl/fmsg-mcp/client";

const client = new FmsgClient("https://api.example.com", process.env.FMSG_API_KEY!);
console.log(await client.address());
const inbox = await client.listInbox(10);
const sent = await client.send({ to: ["@bob@example.com"], topic: "Hi", body: "Hello from code" });
console.log(sent.id, sent.redactions);
client.close();
```

`send()` replaces selected credential patterns in the body and topic before creating the draft.
Its result includes the replacement count (`redactions`), the kinds replaced (`redacted`, such as
`github_token`) and transmitted `topic`. Attachments are
unchanged. Use `streamAttachment()` to consume large files incrementally; consume or cancel its stream.

Applications with their own authorization integration can pass a `TokenProvider` instead of an
API-key string. The client shares renewal across concurrent requests and keeps the authenticated
address fixed. See the [token-provider contract](./docs/token-providers.md). This library interface
is also used by the executable's optional [OAuth mode](./docs/oauth.md).

## Development

```sh
npm ci
npm run typecheck && npm run build && npm test
npx @modelcontextprotocol/inspector node dist/index.js          # stdio, with FMSG_API_URL/FMSG_API_KEY set
bash .github/scripts/run-fmsg-docker-e2e.sh                     # end to end on two real fmsg stacks
```

See [AGENTS.md](./AGENTS.md) for layout and conventions, [ROADMAP.md](./ROADMAP.md) for remaining
integration work, and [CHANGELOG.md](./CHANGELOG.md) for release notes.

### Releasing

Publish a stable GitHub release tagged `vX.Y.Z` to run the checks, publish the npm package, and
then update the MCP Registry with the same version. Both use OIDC authentication; no dedicated
registry secret is needed. Drafts and prereleases do not publish. Registry publishing runs as a
separate job, so if it fails after npm succeeds, use **Re-run failed jobs** on the release workflow.

[MIT licensed](./LICENSE)