Docs

Everything an agent needs

Connection steps, calling tools, call statuses, common errors and plan limits.

Connect

Endpoint: https://www.patchmcp.com/mcp (Streamable HTTP, OAuth 2.1 with PKCE, dynamic client registration and client-ID metadata documents supported). Discovery lives at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server. The consent flow verifies the user's number with a text code, and that verified number is the account; there is no separate sign-up.

  1. Open grok.com/connectors, choose New Connector, then Custom.
  2. Give it this server URL: https://www.patchmcp.com/mcp
  3. A Patch MCP page opens asking for your number. Verify the same phone number with a code by text or call and press Allow. That is the whole sign-up.
  4. Back in Grok, ask for a call: “Call our supplier Northline Parts at +1 202 555 0148. Check whether order #482 has shipped and ask for the expected delivery date.”
  1. In Claude, open Settings → Connectors → Add custom connector.
  2. Give it this server URL: https://www.patchmcp.com/mcp
  3. Click Connect. A Patch MCP page opens asking for your number. Verify the same phone number with a code by text or call and press Allow. That is the whole sign-up.
  4. In a chat, enable the connector and ask Claude to call your supplier with a number and a specific request.
  1. Open ChatGPT Plugins. Select the plus button → Add custom MCP server.
  2. Name it Patch MCP, enter this server URL https://www.patchmcp.com/mcp, and choose OAuth authentication.
  3. Review the connection warning and select Create as a plugin. A Patch MCP page opens asking for your number. Verify the same phone number with a code by text or call and press Allow. That is the whole sign-up.
  4. Install the plugin, start a new chat, type @ and select Patch MCP. Ask for a supplier update.

Custom connections depend on your ChatGPT plan and workspace permissions. If the option is missing, ask your workspace admin.

Tell Claude Code “Connect to https://www.patchmcp.com/mcp to make phone calls.” and it adds the server itself, or run:

claude mcp add --transport http patch-mcp https://www.patchmcp.com/mcp

Run /mcp to connect your number whenever you like; skip it and the first call your agent attempts opens the connect page for you.

Add to .cursor/mcp.json (or the global one):

{ "mcpServers": { "patch-mcp": { "url": "https://www.patchmcp.com/mcp" } } }
codex mcp add patch-mcp --url https://www.patchmcp.com/mcp

Or in ~/.codex/config.toml: [mcp_servers.patch-mcp] with url = "https://www.patchmcp.com/mcp". Then run codex mcp login patch-mcp to connect your number.

Tools

get_phone_number

Returns the authenticated account's connected number as phone_number in E.164 format, plus caller_id_status (verified or unverified). Takes no arguments. This is the user's outbound caller ID; the lookup works even before any calls and when texting is unavailable or SMS consent is off.

estimate_call

Accepts a destination in to (E.164) and checks it against the connected caller ID. Returns available minutes, the allowance percentage for a one-minute call, and rate validity. No call is placed or usage reserved. Prices and eligibility are rechecked when dialing.

place_call

Dials a number from the user's verified caller ID and returns straight away with a call_id and a listen_url; the conversation carries on in the background.

to
Destination in E.164 (+14155551234). Central America, Europe, North America, and South America.
objective
What the call must achieve, with specifics and acceptable fallbacks (10–2000 chars).
locale
Optional language tag: fr, it, ru, pl, uk, ro, nl, or de; English, Spanish, and Portuguese use regional tags such as en-US, es-MX, or pt-BR. Uses your saved voice for that language, otherwise its female default. The objective can be in another language. Defaults to your account locale, then US English; applies only to this call. Choose and preview voices under Account → Voices by language.
callee_name
Who is being called. Optional, improves the conversation.
context
Optional facts and decision authority for the call. Supply needed details and acceptable fallbacks before dialing; there is no private channel to send new instructions during a call.
user_name
The user name supplied with the call, e.g. Sam or Sam at Acme. The default introduction uses “Hi, I’m calling for … about …”; customize the introduction under Account → Call agent instructions. Only needed after a user_name_required error; it is saved for future calls, and a later value updates it.

get_call

Current status and available transcript, plus the resolution and recording_url as they become available after the call. Pass wait_seconds (≤ 50) to long-poll.

end_call

Requests an end to a running call. A connected assistant is asked to say goodbye before hanging up; a call still ringing can be stopped immediately.

set_call_visibility

Publish a call you own with { call_id, is_public: true } to get a permanent, token-free link. Anyone with it can view the call details, transcript, result and audio. Set is_public: false to make it private again. Only do this when the user explicitly asks.

list_calls

The account's latest calls, newest first, each with its status and result.

Texting — coming soon

Texting, picture messages, inbox access and text event subscriptions are unavailable. Text tools return texts_coming_soon; automatic text delivery is paused.

Call lifecycle

Statuses: queued → ringing → in_progress → one of completed, no_answer, busy, voicemail, failed, canceled, declined_recording, opted_out.

Every terminal call carries a resolution: { outcome: achieved | partially_achieved | not_achieved | no_conversation, summary, commitments[], follow_ups[], key_facts[], callee_requested_no_further_calls }. The resolution can lag the terminal status by a few seconds while it is extracted.

Transcript rows are { role: agent | callee | keypad, text, at_ms }. Keypad rows show carrier-accepted number presses, not speech. recording_status moves from processing to available typically 15–90 s after the call ends; private recording_url links expire after about an hour and private listen_url links after four hours. Public call and recording links have no expiration while the call remains public.

Plans

Eligible US/Canadian accounts start with 5 free calls to US/Canada of up to 5 minutes, counted only when someone picks up and speaks. Calls involving other supported countries require a paid plan from the first call. Paid plans are Starter ($10/month), Plus ($25/month), Pro Starter ($100/month), Pro Plus ($250/month), Pro Max ($500/month), with a monthly allowance reported as the percentage left. The message field of place_call states what remains. Texting is coming soon.

Errors

Rejections come back as tool errors with a machine-readable error code and a human message. Relay the message to the user; do not retry blindly.

invalid_number / unsupported_region / blocked_number
The destination is invalid, outside supported countries, or in a blocked range.
unsupported_language
The requested locale is not supported. Choose a language and region offered on the account page.
route_unavailable
The caller-ID and destination route has no current supported rate. No call was placed. Use estimate_call to check availability before dialing.
subscription_required
A paid plan is required for international calls, or the free US/Canada calls are used up. Explain that the action is unavailable with the current account entitlement.
plan_limit_reached
The month's usage will not cover another call (or this text). Includes usage_left_percent, reset_at, retry_after_seconds and manage_url.
caller_id_not_verified
The account's number lost its verification; finish it again at /verify.
user_name_required
The account has no name for the call introduction yet. Ask the user for one and call again with it in user_name.
do_not_call
The destination is on the do-not-call list.
concurrent_call_in_progress
Includes active_call_id; wait or end it first.
objective_rejected
Safety screening declined the objective.
carrier_error / service_unavailable
Temporary provider problems.
sms_consent_required / unsupported_messaging_region
Agent texting requires optional SMS consent and a US or Canadian account number.
texts_coming_soon / opted_out
Text tools only: texting is not available yet (tell the user it is coming soon), or the user texted STOP (they can text START to resume).
invalid_params
An argument failed validation: for send_text, a message with nothing to send, or a picture URL that is not a public https link.

Limits

Read the calling guides →