Docs

Patch MCP: phone workspace and calls for AI agents

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

Patch MCP for AI agents

Patch MCP lets AI agents manage their phone workspace after OAuth: configure agents, numbers, voices and connected tools, run tests, place calls and manage billing.

Connect to https://www.patchmcp.com/mcp using Streamable HTTP and OAuth 2.1 with PKCE. The authorization flow verifies your phone number; it becomes your account and default outbound caller ID. With the phone workspace enabled, list_phone_numbers shows available sources; pass source_number_id to select an enabled, published outbound number.

Start with get_capabilities. Request the needed calls, configuration, numbers, connectors, billing and account scopes, each with :read or :manage; manage includes read. Existing grants do not expand automatically. Omitted scopes retain historical calling access; refresh cannot add permissions. The reference describes this deployment, and feature availability and account limits still apply.

Use revision-checked agent updates for future calls, or save a draft and explicitly publish it. Creation and payment operations use UUID request IDs for safe recovery. Headless synthetic tests run without a browser heartbeat. Third-party consent, payment authentication, own-voice verification and carrier forwarding may still require a person; admin and experimental SMS/events are excluded.

Caller-number eligibility: US/Canada (+1), UK (+44), Brazil (+55), and Norway (+47), including countries and territories sharing those calling codes. Outbound destinations: Central America, Europe, North America, and South America, subject to route availability. Route availability is checked when placing a call. Destination coverage does not expand the numbers that can sign up.

Eligible accounts start with 5 free US/Canada calls of up to 5 minutes. Both numbers must be US/Canadian; other calls require a paid plan. One call runs at a time. See current pricing and usage.

Gather the destination, callee’s local IANA timezone (such as America/Chicago), objective, context and decision limits before place_call. Determine the timezone from reliable context or ask; do not guess from the phone number. Offer the returned listen_url, then poll get_call with wait_seconds up to 50. Once terminal, wait for the resolution if pending and report its outcome and summary. Transcripts and recordings become available separately. There is no private channel for new instructions during the call.

Use Patch for a specific authorized call: book a table, check appointment availability, ask about stock or opening hours, or check an order. Calls are private by default; publish only at the user’s explicit request.

Generated tool reference · Markdown agent guide · JSON reference · Documentation index

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 code by text or automated call, 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.

Other / custom MCP client

  1. Open your client's MCP server or integration settings and add a remote MCP server named Patch MCP. Labels vary by client; use its remote MCP configuration rather than a local command.
  2. Enter the server URL https://www.patchmcp.com/mcp with Streamable HTTP transport and OAuth authentication.
  3. Connect or authorize. On the Patch authorization page, use the same verified phone number as your existing Patch account, complete verification privately, review the requested access and select Allow if you approve.
  4. Return to your client and enable Patch's tools in a chat. Confirm Patch appears connected before requesting a call. Connecting alone does not place a call.
  5. If the client does not support remote Streamable HTTP MCP servers with OAuth, this setup may not work. Check the client's documentation or support instead of guessing a menu path, requesting an API key, or changing authentication.

Tools

These tools are available on this deployment. Descriptions and schemas are generated from the same definitions as MCP tool discovery.

Read schemas and illustrative request/response examples →

Call lifecycle

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

Terminal calls receive a resolution after processing: { outcome: achieved | partially_achieved | not_achieved | no_conversation | unknown, summary, commitments[], follow_ups[], key_facts[], callee_requested_no_further_calls }. Screened-out calls use rejected; a pickup with no detected speech can use answered_silently. The resolution can lag the terminal status while it is extracted. An unknown outcome means review was unavailable or the evidence was insufficient.

Transcript rows are { role: agent | callee | keypad, text, at_ms }. Keypad rows represent keypad actions, not speech. The LiveKit session recording is finalized and copied to private storage after the call. recording_status can become available, failed or none; 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.

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.
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. 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.
invalid_params
An argument failed validation. place_call requires to, objective and the callee’s local IANA timezone in timezone (for example America/Chicago). Determine the timezone from reliable context or ask; do not infer it from the phone number. Check the tool schema and retry with valid arguments.

Limits

Read the calling guides →