fmsg

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

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