Choose MCP or REST for Your iMessage Integration
The one-sentence answer
Use REST when your application code decides what to do. Use MCP when a language model decides.
Both paths share the same Figment Apple Connect OAuth grant and the same two iMessage scopes: messages:read for history and search, and messages:send for outbound messages. The difference is the caller's reasoning model, not the underlying permission contract.
Figment issues these grants, not Apple. Apple's supported third-party account authorization covers Mail, Calendar, and Contacts; there is no Apple-issued iMessage OAuth scope.
What Figment's REST interface gives you
Figment Apple Connect exposes iMessage through a conventional HTTP API at https://figment.so/api/apple-connect. After completing the PKCE authorization flow with your registered client_id, you receive a Figment access token (normally valid for 900 seconds) and a connection_id that identifies the connected Apple Account.
Three read endpoints cover the common patterns:
GET /v1/connections/{connection_id}/chats?limit=20&offset=0
GET /v1/connections/{connection_id}/messages?chatGuid=...&limit=20
GET /v1/connections/{connection_id}/messages/search?query=...&chatGuid=...&limit=20
Use chatGuid values returned by the chats endpoint. When constructing real requests, URL-encode all query parameter values with a URL builder; never paste raw chatGuid strings directly into a query string.
A fourth endpoint handles outbound messages:
POST /v1/connections/{connection_id}/messages/send
The body carries a chatGuid (taken from the chats response) and text. Every send request requires a stable Idempotency-Key header you generate and persist before the first attempt. Poll GET /v1/connections/{connection_id}/messages/receipt with the same key to check delivery state.
REST fits when your code owns the full decision path: a CRM logging a conversation, a support tool routing by keyword, or a scheduled alert pipeline. The logic is explicit and testable.
How MCP changes the caller
Integration design: Figment does not currently ship a hosted MCP server. This section describes building the MCP layer yourself, wrapping Figment's supplied REST endpoints as typed tools. No Figment MCP server endpoint contract has been issued; treat the architecture below as a design guide, not a tested integration.
The Model Context Protocol is an open-source standard for connecting AI applications to external systems. In this integration design, you build an MCP server that exposes Figment's REST operations as typed tools. An LLM running inside a host — Claude Desktop, VS Code, or a custom agentic framework — instantiates an MCP client, discovers the available tools, and calls them when it determines an action is warranted.
Your MCP server translates each tools/call request into the appropriate Figment REST call and returns the result as structured content. The host never touches Figment directly; your MCP server holds the access token and enforces idempotency.
MCP uses JSON-RPC 2.0 over two transports: stdio for local processes and Streamable HTTP for remote servers. The MCP architecture specification recommends OAuth for remote server authentication — which fits naturally with the Figment token flow.
The practical effect: an agent can read recent messages, reason about their content, and decide whether and how to reply — without hardcoded routing logic in your application. This suits AI assistants, agentic task handlers, and CRM copilots where the LLM interprets context before acting.
Two content-trust concerns apply specifically to this path. First, message bodies are untrusted input. A received message can contain text designed to redirect the agent's behavior — a prompt-injection risk. Your MCP server should not forward raw message content as tool arguments or system instructions. Second, writes must be explicit. The send tool should require a resolved chatGuid and final text from the agent — it must not infer or construct those values from conversation context alone. Treat every invocation of the send tool as an explicit authorized write, not an automatic response.
Agent versus application interaction and permission map
This map covers every significant decision axis across the two integration paths.
| Concern | REST — application-driven | MCP — agent-driven (design) |
|---|---|---|
| Who calls the endpoint | Your application code | LLM via tools/call through your MCP server |
| Token holder | Your backend | Your MCP server (same Figment access token) |
| Scopes needed | messages:read, messages:send | Same scopes; server holds the grant |
How chatGuid is selected | Your code retrieves and passes it | Agent uses a prior tool result from the chats listing |
| Idempotency key | App generates one key per intended send before first request | MCP server generates one key per tool invocation; never shared across separate calls |
| Read completeness | Bounded by Mac sync state; check hasMore and historyComplete | Same Mac-sync limit applies; expose these fields in tool output |
| Delivery certainty | Poll /receipt with same key; unknown means poll again, never resend under a new key | Tool returns receipt; unknown means poll only — do not issue a new send |
| Content trust | App controls what text it reads and passes | Message text is untrusted; guard against prompt injection before using it in tool arguments |
| Best for | CRM pipelines, keyword routers, scheduled alerts | AI assistants, agentic task handlers, copilot features |
The grant, Mac dependency, and delivery uncertainty are identical across both paths. Only the decision-making layer differs.
Scope and idempotency rules that apply to both paths
Two rules are non-negotiable regardless of which surface you use.
Exactly two iMessage scopes. messages:read covers both history retrieval and search — there is no separate search permission. messages:send is distinct. A conversation appearing in a read result is not automatically authorized for sends; the send grant must include that exact existing conversation. Request messages:send only when your use case requires outbound messages.
Idempotency is about intent, not content. Generate and persist one key per intended send action before its first request. Reusing a content hash to deduplicate silently merges two separately intended identical messages. A failed send with a given key returns its recorded failure on retry — the key does not trigger a new send attempt. An unknown receipt means poll the same receipt endpoint. It never means issue a new key.
Both paths also share the Mac-sync constraint: read history reflects what is available on the connected Mac. The historyComplete and hasMore fields indicate coverage. Data is bounded even when the connector status shows ready.
Picking your path — or running both
Choose REST when your logic is deterministic: routing rules, response templates, or time-based triggers. It is straightforward to test, easy to reason about, and maps directly to any HTTP client or automation platform.
Choose MCP when the decision of when and what to send belongs to a language model. MCP gives the agent a typed tool contract it can discover and invoke. Your application code stays out of the routing logic entirely.
Run both when your product has deterministic and agentic surfaces. A support product might use REST for SLA-driven auto-replies while an MCP server powers the AI copilot that drafts contextual responses. The grant and scopes are shared; only the caller changes.
Sandbox access is free and uses synthetic data that cannot reach real recipients. Live connections are $29/month per active Apple connection; access starts after setup.
Start your integration
Register your app and explore the sandbox at the developer dashboard. When you're ready to connect a live Apple Account, the Connect Apple Account flow is there.
For a full walkthrough of the PKCE grant and token exchange, see OAuth for iCloud: Connect Apple Data to Your App. For head-to-head alternative comparisons, see Figment vs BlueBubbles, Figment vs AirMessage, and Figment vs Claw Messenger.
