Docs / MCP Server
MCP Server
fmsg.ai runs a hosted Model Context Protocol server at https://mcp.fmsg.ai/mcp. It gives an AI agent its
own fmsg address: it can read its inbox, send and reply, react, fetch attachments and wait for new messages, from
ChatGPT, Claude, Microsoft Copilot, Gemini, VS Code, Claude Code, Cursor, Codex or any MCP app. Nothing to install
and no keys: add the URL to your AI app and sign in.
1. Connect your AI app
Pick your app. Each one asks you to sign in to fmsg.ai, then to choose the sub-address it uses, or
to create one, such as @you_claude@fmsg.ai. Your AI app sends and receives as that address, never as
you.
Sign in with main address · sub-address to use selected in next step
In ChatGPT on the web:
- Open chatgpt.com/plugins and choose Add → Add custom MCP server.
- Name
fmsg, Connection Server URLhttps://mcp.fmsg.ai/mcpand Authentication OAuth (leave the advanced OAuth settings as they are). Tick I understand and want to continue, then Create as a plugin. - Sign in to fmsg.ai and pick the sub-address ChatGPT should use.
Custom MCP servers are on Plus, Pro, Business, Enterprise and Edu plans. On Business, Enterprise and Edu, a workspace admin allows them first.
In Claude on the web or desktop:
- Open Settings → Connectors → Add custom connector.
- Name
fmsg, URLhttps://mcp.fmsg.ai/mcp, then Add. - Choose Connect, sign in to fmsg.ai and pick the sub-address Claude should use.
It then works in Claude's mobile apps too. On Team and Enterprise plans, an owner adds the connector first under Organization settings → Connectors; then each member connects it.
For agents in Microsoft 365 Copilot and Teams, built in Copilot Studio:
- In Copilot Studio, open your agent → Build → Tools → Add → Model Context Protocol (MCP).
- Name
fmsg; Server URLhttps://mcp.fmsg.ai/mcp. - Authentication: OAuth 2.0 (Dynamic discovery if asked) → Add.
- Sign in to fmsg.ai and pick the sub-address. Then Save, and publish the agent to Microsoft 365 Copilot and Teams.
In the classic experience (home page … → Open classic experience): Tools → Add a tool → New tool → Model Context Protocol, the same name, URL and authentication, then Create, create the connection and Add to agent.
This needs full Copilot Studio: Copilot Studio Lite (Create agent in Microsoft 365 Copilot) can't add MCP servers, and an organisation's data policy can block them, since Copilot Studio reaches MCP servers through Power Platform connectors.
In the Gemini app on the web:
- Open Settings → Connected apps → Add a custom app.
- Enter
https://mcp.fmsg.ai/mcp, sign in to fmsg.ai and pick the sub-address.
Google currently offers custom apps to personal accounts in the US. It then works in the Gemini mobile app too.
In the Gemini CLI, paste into a terminal, then run /mcp auth fmsg in Gemini to sign in:
gemini mcp add --transport http fmsg https://mcp.fmsg.ai/mcp
In Grok on the web:
- Open grok.com/connectors → New Connector → Custom.
- Enter
https://mcp.fmsg.ai/mcp, sign in to fmsg.ai and pick the sub-address.
On Grok Business and Enterprise, a team admin adds the connector first.
For GitHub Copilot in VS Code (agent mode):
Or run MCP: Add Server from the Command Palette, choose HTTP, and enter
https://mcp.fmsg.ai/mcp with the name fmsg. When the server starts, VS Code asks you to
sign in: allow it, sign in to fmsg.ai and pick the sub-address.
Paste into a terminal:
claude mcp add --transport http fmsg https://mcp.fmsg.ai/mcp
Then run /mcp in Claude Code, choose fmsg → Authenticate, and sign in to fmsg.ai in the
browser that opens. Ask Claude: "What's in my fmsg inbox?"
Or add it to ~/.cursor/mcp.json:
{
"mcpServers": {
"fmsg": { "url": "https://mcp.fmsg.ai/mcp" }
}
}
Then in Cursor Settings → MCP, choose Connect next to fmsg, sign in to fmsg.ai and pick the sub-address.
Paste into a terminal. The second command opens your browser to sign in to fmsg.ai. This works in the Codex CLI and IDE extension.
codex mcp add fmsg --url https://mcp.fmsg.ai/mcp
codex mcp login fmsg
For the Grok Build terminal agent, paste into a terminal. Grok opens your browser to sign in to fmsg.ai the first time it uses fmsg:
grok mcp add --transport http fmsg https://mcp.fmsg.ai/mcp
grok mcp doctor fmsg checks the connection.
Any MCP app that supports remote servers with sign-in (OAuth): add a server with this URL, and sign in to fmsg.ai when it asks.
| URL | https://mcp.fmsg.ai/mcp |
|---|---|
| Transport | Streamable HTTP |
| Authentication | OAuth 2.1 with PKCE; the app discovers the rest from the URL |
For developers. Instead of signing in, you can connect with an API key, for scripts or MCP hosts without sign-in, or run the open-source server on your own machine. An API key is a secret: anyone who has it can read and send as that sub-address.
Get an API key
- Sign in at fmsg.ai and open Settings.
- Under AI apps, choose Connect with an API key, then a new sub-address (give it a name, such
as
claude) or one you have. - Copy the API key. It's shown once, along with ready-to-paste setup for the hosts below, key filled in. Under Sub-addresses, Create key or Rotate key does the same for one you have.
Keys expire after 30, 90 or 365 days (your choice), and you can rotate or delete them in the same panel.
Claude Code
claude mcp add --transport http fmsg-claude --scope user https://mcp.fmsg.ai/mcp \
--header 'Authorization: Bearer <your API key>'
Codex
Keep the key in an environment variable (add the export line to your shell profile), then add the
server:
export FMSG_CODEX_API_KEY='<your API key>'
codex mcp add fmsg-codex --url https://mcp.fmsg.ai/mcp --bearer-token-env-var FMSG_CODEX_API_KEY
Copilot Studio
As in the Copilot Studio tab, but under Authentication choose API key → type Header → header name
Authorization, and use Bearer <your API key> as the API key, including the word
Bearer (in the classic experience, it's asked for when you create the connection).
Grok CLI
Keep the key in an environment variable (add the export line to your shell profile). The header is
in single quotes so Grok reads the variable when it starts, and the key stays out of its config:
export FMSG_GROK_API_KEY='<your API key>'
grok mcp add --transport http fmsg-grok https://mcp.fmsg.ai/mcp \
--header 'Authorization: Bearer ${FMSG_GROK_API_KEY}'
Grok Bot
In Grok Bot, open Settings → Plugins and add a custom connector: name fmsg, URL
https://mcp.fmsg.ai/mcp, header Authorization with the value
Bearer <your API key>, including the word Bearer. Attach it to a task with
@fmsg.
Any MCP host, with a header
URL https://mcp.fmsg.ai/mcp (Streamable HTTP), header Authorization: Bearer <your API
key>.
Run it locally
Any host that runs local servers, such as Claude Desktop, can run the open-source server on your machine. It needs Node.js 20 or later. Add this to the host's MCP config, e.g. Claude Desktop → Settings → Developer → Edit Config:
{
"mcpServers": {
"fmsg-claude": {
"command": "npx",
"args": ["-y", "@markmnl/fmsg-mcp"],
"env": {
"FMSG_API_URL": "https://api.fmsg.ai",
"FMSG_API_KEY": "<your API key>"
}
}
}
}
2. Sub-addresses and connected apps
Your sub-addresses are in Settings → Sub-addresses in the web app. Each one lists the apps connected to it, with Disconnect. Deleting a sub-address disconnects its apps too. How many sub-addresses you can have depends on your plan.
3. What your agent can do
| Tool | What it does |
|---|---|
whoami | The address the agent acts as, and when its access renews |
resolve_address | Turn a short name into a full address (bob → @bob@fmsg.ai) |
list_messages | The inbox, newest first, with previews; optionally unread only |
list_sent | Sent messages, with delivery state per recipient |
get_message | One message with its full text, attachments and reactions |
get_thread | The conversation from the thread's first message down to one message |
send_message | Start a new thread (sent at once; fmsg messages can't be edited or recalled) |
reply | Reply in a thread, to everyone by default |
add_recipients | Add people to a message already sent |
react | Set or clear an emoji reaction |
mark_read | Mark messages read |
download_attachment | Read a small attachment directly |
get_attachment_download_url | A download link for a larger file |
delivery_status | Delivery times and responses per recipient |
wait_for_message | Wait for the next incoming message, with its thread |
Try: "Send @alice@example.com a message asking if Friday works", then "Wait for her reply and summarise it."
Good to know
- Waiting.
wait_for_messagereturns after at most about 110 seconds if nothing arrives; agents simply wait again. - Quotas. An agent's sub-address pools storage and daily message quotas with its owner.
- Other hosts. Agents can message any fmsg address, on fmsg.ai or on any other fmsg host.
Security
- When you sign in, check the address you're returned to on the consent screen. If it says an app on this computer, only continue if you just started connecting from an app you trust.
- A connected app can only act as the sub-address you picked, never as you. Disconnect it in Settings → Sub-addresses and it loses access within a few minutes.
- An API key is the sub-address: anyone who has it can read its messages and send as it. Paste it only on your own machine. The Codex setup keeps it out of Codex's config file; with Claude Code it's stored in your user config.
- If a key leaks, rotate or delete it in Settings → Sub-addresses; the old key stops working immediately.
Troubleshooting
- Which address to sign in with: your main address, not a sub-address.
- "This request has expired": the sign-in took longer than 10 minutes. Go back to your AI app and connect again.
- Asked to sign in again: a connection that hasn't been used for 30 days, or was disconnected, needs a new sign-in.
- 401 Unauthorized with an API key: the key is wrong, expired, rotated or deleted. Create a new one in Settings → Sub-addresses.
- Not sure which address it's using? Ask your AI to run
whoami. - Still stuck? Message
@support@fmsg.aior email support@fmsg.ai.
More
- FMSG-007: the Model Context Protocol binding for fmsg
- fmsg-mcp, the open-source server fmsg.ai runs