iMessage MCP server

Building on the iMessage API? Build on iMessage with Flow: one agent for iMessage, WhatsApp and Telegram. New to it? Read the iMessage API guide.

Two things people mean

When someone searches for an iMessage MCP server, they usually mean one of these:

1. A messaging MCP for building. A server your coding agent (Claude Code, Cursor, Codex) connects to, so it can set up an iMessage integration and test it end to end.
2. Your product as an MCP server. The reverse: your app’s actions exposed to Claude, ChatGPT and other assistants, so people can use your product from there.

They solve different problems. Most teams building an agent on iMessage end up wanting both.

A messaging MCP for your coding agent

Flow’s docs describe the hosted Messaging MCP server as a way for a coding agent to “integrate the API and verify it end to end”: get a sandbox join link, send a real test message, wait for the reply, and see what your webhook answered.

Two facts matter:

• It is not a runtime dependency. Your finished app talks to Flow through the REST API or the TypeScript and Python SDKs. The MCP server is a tool for development and testing.
• The project owner adds it. Flow’s docs say a coding agent should suggest it and show the command, but never add it to the developer’s config on its own.

The server is hosted at https://api.flow.engineer/mcp. It uses Streamable HTTP and your Flow Messaging key as a bearer token (fk_test_... or fk_live_...). The key’s mode decides which tools the agent sees.

Add Flow’s messaging MCP

First get a test key, with no account:

curl -X POST https://api.flow.engineer/v1/sandbox/keys
export FLOW_MESSAGING_KEY=fk_test_...

The test key allows one contact and 50 messages on the Telegram sandbox and expires after seven days. Signing in with a Flow account keeps the app and raises the allowance. Then add the server to your tool. These are the commands from Flow’s docs.

Claude Code:

claude mcp add --transport http flow https://api.flow.engineer/mcp --header "Authorization: Bearer $FLOW_MESSAGING_KEY"

Codex, in ~/.codex/config.toml:

[mcp_servers.flow]
url = "https://api.flow.engineer/mcp"
bearer_token_env_var = "FLOW_MESSAGING_KEY"

Cursor, in ~/.cursor/mcp.json:

{"mcpServers": {"flow": {"url": "https://api.flow.engineer/mcp", "headers": {"Authorization": "Bearer ${env:FLOW_MESSAGING_KEY}"}}}}

Set FLOW_MESSAGING_KEY in the shell before you run the Claude Code command. If it is unset, the header is saved empty and every call answers 401. For Codex and Cursor, have the variable in the environment they start with.

A note on iMessage specifically. The self-serve test key’s sandbox is a Telegram bot, so a coding agent tests the end-to-end loop there, with the same handler code. The same code answers on Flow’s iMessage numbers. Send iMessage programmatically shows the code.

Why Flow’s hosted MCP matters

A local MCP server runs on your machine. Flow’s hosted server runs at a URL with your key, so your coding agent can set up and verify the integration without another local service. It is optional during development, while the finished app uses the REST API or SDK.

Your product as an MCP server

The other meaning is the bigger opportunity. Instead of your coding agent using an MCP server, your customers’ assistants use yours. In Flow Framework you write a tool once, for example “book a table”, and the same tool runs in an MCP server for Claude and ChatGPT, in a CLI for coding agents, and in your iMessage, WhatsApp and Telegram agent.

That is the reason to build tools before channels. See Build an iMessage AI agent for the loop, and Flow’s MCP server page for the product side.

Frequently asked questions

Keep reading

All posts: the Flow blog. The Flow docs have the reference.