fmsg MCP server

fmsg-mcp

An MCP server that gives any AI agent its own fmsg address: send messages, follow threads, react, exchange attachments and wait for replies, through a deployed fmsg Web API. 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. Operators can enable this with HTTP OAuth.

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

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:

{
  "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.

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: 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:

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 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
edit_message	Change the body of a message you sent, or revert it to the original (FMSG-008 edit; needs a host with FMSG-003 v0.5.0). Edited messages read as edited and carry edited; edit messages themselves are never listed
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 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 and combined 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 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. 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. 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: 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. save_attachment and authenticated HTTP downloads avoid that encoding and keep file bytes out of model context. See issue #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.