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. Works with Claude Code, Claude Desktop, Cursor, VS Code, claude.ai remote connectors and any other MCP host.

• 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.
• The fmsg Web API client is exported for reuse: import { FmsgClient } from "@markmnl/fmsg-mcp/client".

1. Get an fmsg address and API key

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

• No host yet? Create an account at a public fmsg host such as fmsg.io and add an agent (sub-account) to get an API URL and key.
• Self-hosting? Run the stack with fmsg-docker and issue a key with fmsg-webapi api-key create.

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 and /fmsg:reply 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 npx -y @markmnl/fmsg-mcp --http 0.0.0.0:8765
# or
docker build -t fmsg-mcp . && docker run -e FMSG_API_URL=https://api.example.com -p 8765:8765 fmsg-mcp

The MCP endpoint is /mcp; /healthz reports liveness. Point a host at it with Authorization: Bearer fmsgk_... — for claude.ai, add a custom connector with that URL and header; for Claude Code, claude mcp add --transport http fmsg 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. 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.

Tools

Every tool returns readable Markdown plus structuredContent. Ids are decimal strings. Message bodies are labelled as data from other parties, not instructions.

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.

Configuration

The API key is exchanged for a short-lived access token that the server renews automatically.

Over stdio the server also starts with no credentials at all, so hosts and directories can list its tools; every tool call then returns a message naming the missing variables.

Safety

• Sent messages cannot be edited or recalled; send tools say so in their descriptions and are annotated destructiveHint so hosts can ask for confirmation.
• API keys, tokens and other secret-shaped strings are redacted from outbound bodies, topics and error text; the count of redactions is reported.
• Nothing about message size or acceptance is assumed: the fmsg host's own responses and delivery codes are surfaced verbatim.
• See SECURITY.md.

Using the client library

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);
await client.send({ to: ["@bob@example.com"], topic: "Hi", body: "Hello from code" });

Development

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 for layout and conventions.

MIT licensed