fmsg-mcp is an MCP server that provides any AI agent with an independent fmsg address, enabling it to send and receive federated messages through a deployed fmsg Web API. It supports features such as inbox, conversation threads, replies, emoji reactions, attachment exchange, and waiting for new messages.
Key Capabilities
- Assigns fmsg addresses to AI agents to enable message sending and receiving.
- Supports conversation thread tracking, replies, emoji reactions, and attachment exchange.
- Provides the ability to wait for new messages, keeping the request open for up to 230 seconds (controlled by FMSG_MCP_WAIT_MAX_SECONDS).
- All tools return readable Markdown and structured content (structuredContent).
- Provides the resources fmsg://message/{id} and fmsg://thread/{id}, as well as the prompts chat and reply.
- Supports saving attachments directly to disk via the save_attachment tool (requires configuring FMSG_MCP_DOWNLOAD_DIR), avoiding file bytes entering the model context.
- Supports obtaining an HTTPS download link for remote attachments via get_attachment_download_url.
- Selectively redacts sensitive information (such as API keys, tokens, etc.) in outbound messages.
Usage
Connection Methods
- OAuth: Obtain an OAuth-capable MCP URL from an fmsg hosting provider, add it to the AI host, and log in. No API key or local installation is required.
- API Key: Authenticate using an API key issued by an fmsg host (fmsgk_…). Can be installed locally or used over HTTP.
Local Installation (stdio)
- Requires Node.js 22 or later.
- Configure an address via two environment variables.
- Add a server entry in hosts such as Claude Desktop, Cursor, and VS Code; configuration file locations differ (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code: .vscode/mcp.json).
Remote Mode (Streamable HTTP)
- One endpoint serves multiple users, with each client sending its own fmsg API key as a bearer token.
- The MCP endpoint is /mcp, and /healthz reports liveness status.
- HTTP OAuth can be configured to enable browser login, or FMSG_MCP_AUTH_MODE=oauth+api-key can be used to accept both methods simultaneously.
- When deployed behind a TLS-terminating reverse proxy, FMSG_MCP_ALLOWED_HOSTS and FMSG_MCP_ALLOWED_ORIGINS must be set.
Client Library
- You can import { FmsgClient } from "@markmnl/fmsg-mcp/client" to reuse the Web API client.
- The send() method replaces credential patterns in the body and subject before creating a draft, returning the replacement count and types.
- Supports the TokenProvider interface for custom authorization integration.
Use Cases
- Scenarios that require federated message communication between AI agents.
- Scenarios involving multi-agent collaboration and automated tasks that require message passing and waiting for replies.
- Scenarios that require exchanging file attachments but wish to avoid file contents entering the model context.
- AI host environments for local development or remotely shared deployment.
Limitations
- No built-in hosting provider or identity provider; users must choose their own or self-host.
- Sent messages cannot be edited or recalled.
- Inline attachment downloads are limited to 256 KiB by default; larger files require save_attachment or get_attachment_download_url.
- Remote file downloads require the AI host to support authenticated HTTP downloads; a normal browser click will return 401.
- Message size and acceptance policies are enforced by the fmsg host service; MCP only forwards operations and displays upstream errors.
- The redaction feature is not a general-purpose data loss prevention or binary attachment scanning tool.
- The output schema is open and incremental; schemas cached by older versions may reject new fields, requiring the connector to be re-added.
- The wait-for-message feature requires an agent idle timeout of at least 240 seconds.
- Requires Node.js 22 or later.
