How to connect Claude Code or Cursor to an iMessage number with MCP

What does the ZeroSettle connector do?

The ZeroSettle connector lets an AI coding agent get you an iMessage number, build the server that will use it, and test that server against your own number; it is not a way to message customers. ZeroSettle is an iMessage API: a real phone number on real iMessage, running on Apple hardware we operate for you, that your code texts customers from and hears back on through a bearer token and signed webhooks.

The server the agent builds receives on a webhook and replies with POST /api/imessage/send; the connector's own send and read tools exist only to test it.

get_line, sign_up, set_profile, send_test_message, subscribe and read_docs work before you pay; the rest need an active subscription. A failure, including a 402 or a sign-up that finds no free number, comes back as a tool result marked as an error rather than an HTTP error, so the agent can read it and tell you.

How to add the connector to Claude Code, Claude, Cursor or Grok

Every documented client points at https://portal.zerosettle.io/mcp, and all but the xAI API sign you in with OAuth. Under the MCP authorization spec, a client finds the sign-in server from the MCP server itself and must use PKCE; ZeroSettle also supports the dynamic client registration the spec recommends, so the URL alone is enough.

Anthropic's help center says Claude's Free plan allows one custom connector; on Team and Enterprise an owner adds it in Organization settings first, then each member connects. For ChatGPT or any agent with a shell, paste the setup prompt from the ZeroSettle iMessage API docs with an API token from the console, or start from one line: "implement the ZeroSettle iMessage API according to https://portal.zerosettle.io/docs.md".

Claude Code

claude mcp add --transport http zerosettle https://portal.zerosettle.io/mcp

Then run /mcp, pick zerosettle and choose Authenticate. Adding --scope project to the command writes the server to a .mcp.json your team can commit; Claude Code asks each teammate to approve a project-scoped server before using it.

Cursor

Use the Add to Cursor link in ZeroSettle's connect-your-AI-agent docs, or put this in .cursor/mcp.json (one project) or ~/.cursor/mcp.json (every project). Cursor finds the OAuth flow from the URL, so the file holds no token.

{
  "mcpServers": {
    "zerosettle-imessage": { "url": "https://portal.zerosettle.io/mcp" }
  }
}

Grok and the xAI API

An app that embeds Grok passes the connector as an mcp tool in a request to xAI's Responses API, with a static token minted in the ZeroSettle console and read from the environment. On grok.com, use Connectors → New Connector → Custom and sign in.

import os

zerosettle_tool = {   # goes in the tools list of a https://api.x.ai/v1/responses request
    "type": "mcp",
    "server_url": "https://portal.zerosettle.io/mcp",
    "server_label": "zerosettle-imessage",
    "authorization": f"Bearer {os.environ['ZEROSETTLE_TOKEN']}",
}

How to sign up and get a number from the agent

Run the get-started prompt, or say "get me an iMessage number", and the agent runs ZeroSettle's sign-up as tool calls; only the payment happens in a browser.

1. get_line reports onboarding (sign_up, claim, test, subscribe or ready) with a next hint.
2. sign_up claims a free number for your use_cases: sign_in, branded_messages or ai_agent. A Growth signup link's token goes in invite.
3. set_profile sets the brand name and photo recipients see.
4. send_test_message texts your own number and shares that name and photo.
5. subscribe returns a Stripe Checkout link. After you pay, get_line shows active: true.

A number not paid for within 30 minutes is released, and until the subscription is active the API answers 402 to everything. Numbers can run out; if all are taken, you can join the waitlist. Pro is $49/month with a 30-day money-back guarantee; see ZeroSettle pricing for Growth.

How to build your use case with a prompt

ZeroSettle's four build prompts each scaffold one integration in your stack: the prompt carries your account's state and the matching docs section, has the agent read the webhook and compliance sections, then walks it through the build, the API key, the webhook and a check on your own number. Claude Code shows them as slash commands such as /zerosettle:build-sign-in; Cursor and Claude list them in the prompts menu.

Pass stack (for example "Node + Express on Fly.io") or the agent asks. See also an AI agent on your own model and Sign in with iMessage.

How the agent wires your server: API key, webhook, test

Wiring your server takes four connector steps: create_api_key, set_webhook, test_webhook, and one send_imessage to your own number.

1. API key: create_api_key mints your server's bearer token, shown once. It belongs in the server's environment, never in source. Minting again revokes nothing; revoking revokes all.
2. Webhook: the agent exposes the receiver (locally, cloudflared tunnel --url http://localhost:8100) and calls set_webhook(url). The signing secret is shown once; calling again rotates it.
3. Test event: test_webhook POSTs a signed synthetic message.received (id 0, "test": true, header X-ZeroSettle-Test: 1) and reports your receiver's status, latency and error. It is not retried and not recorded as a delivery.
4. Round trip: send_imessage texts your own number, you reply, and list_messages shows whether your server answered.

The test event is signed like a real one, so the receiver verifies it first and can then skip the business logic on the X-ZeroSettle-Test header. This FastAPI receiver uses the docs' verifier and dedupes on message.id plus event; how ZeroSettle webhooks work covers retries.

# receiver.py: run with  uvicorn receiver:app --port 8100
import hashlib, hmac, json, os, time
from fastapi import FastAPI, Request, Response

app = FastAPI()
SECRET = os.environ["ZEROSETTLE_WEBHOOK_SECRET"]
seen: set[tuple[int, str]] = set()           # use a durable store in production

def verify(header: str, raw: bytes, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        t, v1 = int(parts["t"]), parts["v1"]
    except Exception:
        return False
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(SECRET.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

def enqueue(message: dict) -> None:
    print("inbound", message["id"], message["handle"])   # hand off to your worker here

@app.post("/webhook")
async def webhook(req: Request):
    raw = await req.body()
    if not verify(req.headers.get("X-ZeroSettle-Signature", ""), raw):
        return Response(status_code=401)
    if req.headers.get("X-ZeroSettle-Test") == "1":
        return {"ok": True}                  # test_webhook: signature passed
    ev = json.loads(raw)
    if ev["event"] == "message.received":
        key = (ev["message"]["id"], ev["event"])   # retries repeat this pair
        if key not in seen:
            seen.add(key)
            enqueue(ev["message"])           # answer 2xx now, reply from the worker
    return {"ok": True}

When test_webhook or the round trip fails

A failed check comes down to the URL, reachability, the signature check or the 10-second answer.

test_webhook is not recorded as a delivery, so last_delivery in GET /api/imessage/line shows only real events, such as the message.sent from the round-trip text, with its status code and error:

export BASE=https://portal.zerosettle.io
curl -s -H "Authorization: Bearer $ZEROSETTLE_TOKEN" $BASE/api/imessage/line

Can I skip the server and use ZeroSettle's hosted AI agent?

Yes. With no server, set_agent with managed_by: "zerosettle" and a business_context hands your number to ZeroSettle's hosted AI agent (Managed by AI Agent, Beta), which answers every inbound text from your business context. start_conversation opens new threads.

• Replace the example first. The business context is required, up to 40,000 characters, and defaults to a made-up business. Have the agent call read_docs("agent") before writing it.
• Either-or per number (per line group on Growth). Inbound texts no longer reach your webhook, and sends from the connector's send_imessage, the API or the console are refused with 403 managed_by_zerosettle. Test by texting the number yourself.
• AI credits. One per text the hosted agent sends; Pro includes 1,000 a month and Growth 5,000.

managed_by: "api" hands the number back to your server. Settings are in how ZeroSettle's hosted AI agent answers iMessages.

Which ZeroSettle limits and rules bind the agent?

The connector's send_imessage is the same call as POST /api/imessage/send, so ZeroSettle's new-contact limits, STOP enforcement and consent rules bind the agent and the code it writes. ZeroSettle sets the limits to protect the number's standing with Apple, and they apply to every caller, the console included.

• New-contact limits: on 429 new_contact_limit, the code should wait retry_after_s. Anyone who texted the line first, and any ongoing conversation, is never limited.
• STOP: a text with the word STOP in it, or a clear request like “take me off your list”, opts the sender out of every number on your account, and texts, voice messages, photos, reactions, typing and name-and-photo shares to them return 403 recipient_opted_out. Code should never retry it; only their START opts them back in (how STOP works on ZeroSettle).
• Consent: message only people who gave you their number for this purpose; in the US, TCPA statutory damages run $500 to $1,500 per message. Have the agent call read_docs("compliance") (and see the TCPA consent guide). This isn't legal advice.

More setup guides are in the ZeroSettle guides hub and plans are under pricing. To start without an agent, get a number in the console and read how to send an iMessage from code without a Mac.