Connect iMessage to MCP Clients and AI Agents

Giving an AI agent access to iMessage means solving two problems at once: getting authorized, scoped access to the user's messages, and exposing that access through a protocol the agent understands. Figment handles the first part — a user-approved OAuth grant that your app exchanges for an access token, not the user's Apple password. Your local MCP adapter handles the second part, translating tool calls into authenticated REST requests against Figment's API.

What the adapter enables

The adapter wraps four iMessage operations:

• List conversations — paginated chat list; each chat returns a guid used as chatGuid in subsequent calls
• Message history — paginated messages per conversation; check hasMore and historyComplete before assuming full coverage
• Search — scans messages available on the connected Mac; pagination is bounded by documented limits; not a guaranteed complete index
• Send — posts to an existing conversation included in the user's send grant; requires a stable idempotency key

When Messages in iCloud is enabled, SMS, MMS, and RCS threads sync alongside iMessage. The iPhone must be on, connected to a network, and signed in to the same Apple Account for new traffic to reach the Mac (see Apple: carrier forwarding setup). Previously synced carrier-message history can remain on the Mac when the iPhone goes offline — but phone availability directly affects any new messages that have not yet synced. historyComplete: false does not prove complete iCloud history.

Connection lifecycle

Each Apple service reports its own state independently of the account sign-in. The iMessage connector can reach any of these states: connecting, needs_approval, syncing, ready, offline, reconnect_required, revoked.

Your adapter should validate the grant at startup and handle API errors at call time. Non-ready or revoked connectors return non-2xx responses rather than a diagnostic state object — treat those as errors and surface setup guidance to the user. Direct users to /apple-connect/account for connection status and resolution. A ready state does not guarantee complete message history or delivery.

Adapter tool design

The table below is a custom adapter design — these are suggested tool names for your MCP server, not Figment product tools. There are exactly two iMessage scopes: messages:read covers listing, history, and search; messages:send is a separate grant for outbound sends.

Request only the scopes your agent needs. A conversation returned by list_chats is not automatically authorized for sends — the user's messages:send grant must explicitly include that existing conversation. A selected-conversation read grant requires chatGuid for both history and search; encode all query parameter values with a URL builder and do not paste raw strings directly into GET URLs.

Credentials and local adapter architecture

Register your app at /apple-connect/developers. Figment is the token issuer — this is not an Apple-issued credential and is not related to Sign in with Apple. Access tokens are opaque strings that normally expire after 900 seconds; store and rotate refresh tokens separately per grant; refresh calls must be serialized per grant and replacement refresh tokens saved. Token refresh is application work in your adapter.

There is no published Figment MCP server package or remote MCP URL. You build and run a local process — typically a Node script or similar — that reads credentials from a protected environment or secret store at startup. Never place a live token value in a shared or version-controlled config file. Your adapter is responsible for loading credentials from its own protected environment or secret store — do not rely on a host application to expand environment-variable references or retrieve secret values from an OS keychain automatically. For general host configuration, see local server setup.

Sending messages safely

submitted means the bridge accepted the request — not that the message was delivered. Generate and persist one stable idempotency key per intended action before the first request, bound to the exact payload. Reuse it only for that same action and body — a body hash alone can wrongly merge two separately intended identical messages.

Receipt states: submitted, delivered, read, failed, unknown, simulated (sandbox). A failed receipt does not automatically retry — repeating the request with the same key returns the same recorded result. If state is unknown, poll only; never resend under a new key. Receipt envelope: {data:{idempotencyKey,state,guid?,delivery?,retrySend?},mode,replayed}. Sandbox responses carry mode:"sandbox" and state:"simulated".

Pricing

The developer pays $29 per month per active live Apple connection. Sandbox is free — synthetic conversations, no real message delivery, no charge. Access starts after setup. Manage grants at /apple-connect/account.

Connect Apple Account to register your app and start building.