{
  "format": "patch-agent-reference",
  "formatVersion": 1,
  "name": "Patch MCP",
  "description": "Patch MCP gives AI agents outbound phone-calling tools: call businesses from your verified caller ID and retrieve structured results, transcripts and recordings when available.",
  "website": "https://www.patchmcp.com/",
  "documentation": "https://www.patchmcp.com/docs",
  "pricing": "https://www.patchmcp.com/pricing",
  "endpoint": "https://www.patchmcp.com/mcp",
  "transport": "streamable-http",
  "authentication": {
    "type": "OAuth 2.1",
    "pkce": true,
    "dynamicClientRegistration": true,
    "clientIdMetadataDocuments": true,
    "protectedResourceMetadata": "https://www.patchmcp.com/.well-known/oauth-protected-resource/mcp",
    "authorizationServerMetadata": "https://www.patchmcp.com/.well-known/oauth-authorization-server",
    "onboarding": "Verify your phone number during authorization; the verified number is the account and outbound caller ID."
  },
  "eligibility": {
    "callerId": "US/Canada (+1), UK (+44), Brazil (+55), and Norway (+47), including countries and territories sharing those calling codes",
    "callerIdCallingCodes": [
      "1",
      "44",
      "55",
      "47"
    ],
    "callerIdCountries": [
      "AG",
      "AI",
      "AS",
      "BB",
      "BM",
      "BR",
      "BS",
      "CA",
      "DM",
      "DO",
      "GB",
      "GD",
      "GG",
      "GU",
      "IM",
      "JE",
      "JM",
      "KN",
      "KY",
      "LC",
      "MP",
      "MS",
      "NO",
      "PR",
      "SJ",
      "SX",
      "TC",
      "TT",
      "US",
      "VC",
      "VG",
      "VI"
    ],
    "destinationRegions": "Central America, Europe, North America, and South America",
    "destinationCountries": [
      "BZ",
      "CR",
      "SV",
      "GT",
      "HN",
      "NI",
      "PA",
      "AX",
      "AL",
      "AD",
      "AT",
      "BE",
      "BA",
      "BG",
      "HR",
      "CY",
      "CZ",
      "DK",
      "EE",
      "FO",
      "FI",
      "FR",
      "DE",
      "GI",
      "GR",
      "GL",
      "GG",
      "HU",
      "IS",
      "IE",
      "IM",
      "IT",
      "JE",
      "LV",
      "LI",
      "LT",
      "LU",
      "MK",
      "MT",
      "MC",
      "ME",
      "NL",
      "NO",
      "PL",
      "PT",
      "XK",
      "RO",
      "RU",
      "SM",
      "RS",
      "SK",
      "SI",
      "ES",
      "SJ",
      "SE",
      "CH",
      "UA",
      "GB",
      "VA",
      "US",
      "CA",
      "MX",
      "PM",
      "AR",
      "BO",
      "BR",
      "CL",
      "CO",
      "EC",
      "FK",
      "GF",
      "GY",
      "PY",
      "PE",
      "SR",
      "UY",
      "VE"
    ],
    "locales": [
      "en-US",
      "en-GB",
      "en-AU",
      "en-CA",
      "en-IN",
      "es-MX",
      "es-ES",
      "es-CO",
      "es-AR",
      "es-CL",
      "pt-BR",
      "pt-PT",
      "fr",
      "it",
      "ru",
      "pl",
      "uk",
      "ro",
      "nl",
      "de"
    ],
    "routeAvailability": "Use estimate_call; destination coverage does not imply caller-number eligibility.",
    "free": {
      "calls": 5,
      "maxDurationMinutes": 5,
      "bothNumbersMustBeUSOrCanadian": true
    },
    "internationalCallsRequirePaidPlan": true,
    "concurrentCallsPerAccount": 1,
    "textingAvailable": false
  },
  "workflow": [
    "Connect and complete OAuth and number verification.",
    "Get the connected caller ID with get_phone_number and check the destination with estimate_call.",
    "Gather the destination, objective, facts, decision limits and acceptable fallbacks before place_call.",
    "Offer the returned listen_url; poll get_call with wait_seconds up to 50 until terminal, then wait for resolution if still pending.",
    "Report resolution.outcome and summary; a completed call does not by itself mean the objective succeeded."
  ],
  "tools": [
    {
      "name": "estimate_call",
      "description": "Check route availability, estimated one-minute usage, and remaining allowance before dialing. Calls in Central America, Europe, North America, and South America. Calls involving any non-US/Canadian number require a paid plan. Uses the verified caller ID and destination to price the route. Uses cached routing data or dialed prefixes without a paid lookup. Does not place a call, send a code, or reserve plan usage. Estimates expire and are rechecked before dialing.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "description": "Destination in E.164 format, including country code."
          }
        },
        "required": [
          "to"
        ],
        "additionalProperties": false
      },
      "annotations": {
        "title": "Estimate call",
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": true
      }
    },
    {
      "name": "place_call",
      "description": "Place the call FROM the authenticated user's own verified phone number to accomplish a specific objective (book a table, ask a question, chase an order). A real-time voice agent handles the call, including automated phone menus and hold queues. Its default opening says who it is calling for and states the call's purpose. Users can customize the introduction and conversation style under Account → Call agent instructions; saved instructions apply to new calls, with the objective, context and other call details added by the server. The first spoken turn to a human must still include the recording disclosure in the resolved call language (English: \"This call is being recorded.\") after the introduction and before the first business question or request. Returns immediately with a call_id and resolved locale, language, and voice; the call proceeds in the background and typically takes 2–5 minutes — poll get_call (pass wait_seconds to long-poll) until the status is terminal. The response includes a listen_url: a private web link where the user can hear the call live, watch the transcript, and stop the call — offer it to the user. Calls in Central America, Europe, North America, and South America, subject to route availability; never for emergencies. Calls involving a non-US/Canadian number require a paid plan from the first call. Rates vary by caller ID and destination; use estimate_call to check available minutes. Paid usage follows telephone, AI and any lookup costs, including unsuccessful attempts, and can update after the call. Calls can be placed at any time of day, any day of the week, and the user is responsible for fair use; one call runs at a time per account and volume is governed by the plan — rejections return a machine-readable `error` code with retry guidance, so relay the message to the user rather than retrying blindly. The voice agent receives the name of the person the call is for: if the account has no name on file the call is rejected with `user_name_required` — ask your user what name to give (e.g. \"Sam\" or \"Sam at Acme\"), then call again with it in `user_name`; it is saved to the account for future calls.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "locale": {
            "type": "string",
            "enum": [
              "en-US",
              "en-GB",
              "en-AU",
              "en-CA",
              "en-IN",
              "es-MX",
              "es-ES",
              "es-CO",
              "es-AR",
              "es-CL",
              "pt-BR",
              "pt-PT",
              "fr",
              "it",
              "ru",
              "pl",
              "uk",
              "ro",
              "nl",
              "de"
            ],
            "description": "Language the voice agent should use for the entire call, as a supported BCP 47 tag: fr, it, ru, pl, uk, ro, nl, or de (no regional variants), or a regional locale such as en-US (US English), es-MX (Mexican Spanish), or pt-BR (Brazilian Portuguese). The objective and context may be written in another language. Defaults to your account locale, or en-US. Uses your saved voice for that locale, otherwise its default female voice. Applies only to this call; the selected language stays fixed for the entire call. Unsupported locales return unsupported_language before dialing."
          },
          "callee_name": {
            "description": "Who is being called, e.g. \"Zuni Café\". Improves the conversation and the logs.",
            "maxLength": 200,
            "type": "string"
          },
          "context": {
            "description": "Extra facts the agent may reveal if asked (e.g. party preferences, callback number policy).",
            "maxLength": 2000,
            "type": "string"
          },
          "objective": {
            "description": "What the call should achieve, with all needed specifics and acceptable fallbacks. E.g. \"Book a table for 2 tonight at 19:30 under 'Iddo'. Acceptable window 19:00–20:30.\"",
            "maxLength": 2000,
            "minLength": 10,
            "type": "string"
          },
          "to": {
            "description": "Destination phone number in E.164, e.g. +14155551234. Supported: Central America, Europe, North America, and South America (Telnyx regions; Caribbean excluded). Destination country codes: BZ, CR, SV, GT, HN, NI, PA, AX, AL, AD, AT, BE, BA, BG, HR, CY, CZ, DK, EE, FO, FI, FR, DE, GI, GR, GL, GG, HU, IS, IE, IM, IT, JE, LV, LI, LT, LU, MK, MT, MC, ME, NL, NO, PL, PT, XK, RO, RU, SM, RS, SK, SI, ES, SJ, SE, CH, UA, GB, VA, US, CA, MX, PM, AR, BO, BR, CL, CO, EC, FK, GF, GY, PY, PE, SR, UY, VE.",
            "type": "string"
          },
          "user_name": {
            "description": "The user name supplied to the voice agent for the call, e.g. \"Sam\" or \"Sam at Acme\". The default introduction uses it in \"Hi, I’m calling for … about …\"; a custom introduction follows the saved Account → Call agent instructions. Only needed when place_call returned user_name_required: ask your user for it, do not invent one. Saved to the account for future calls; a later value updates the saved name.",
            "maxLength": 60,
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "to",
          "objective"
        ],
        "type": "object"
      },
      "annotations": {
        "title": "Place call",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      }
    },
    {
      "name": "get_call",
      "description": "Get the status and, once terminal, the structured resolution of a call started with place_call. Returns instantly by default. Pass wait_seconds (max 50) to have the server hold the request and return early on any status change — fewer round trips while a call is in progress. Terminal statuses: completed, no_answer, busy, voicemail, failed, rejected, canceled, declined_recording, opted_out. rejected means safety screening declined the objective before dialing; error.message and resolution.summary explain why. Terminal calls include a `resolution` {outcome: achieved|partially_achieved|not_achieved|no_conversation, summary, commitments[], follow_ups[], key_facts[]} — read it before the transcript; it is the answer. Completed calls also carry the transcript (may be marked transcript_truncated) and a recording_url the user can listen to (private links expire after ~1 hour). The resolution can lag the terminal status by a few seconds while it is extracted. Calls include the resolved locale, language, voice, and is_public; public calls return token-free listen and recording URLs that remain accessible while public. Use set_call_visibility only when the user explicitly asks to publish or make private. Every call includes a listen_url — the call page for the user (live audio + transcript while in progress; recording + transcript once ended). ended_by='user' on a canceled call means the user deliberately stopped it from that page — don't retry. recording_status=processing means the recording is still being prepared by the carrier (typically ready 15–90s after the call ends) — call get_call again, or pass wait_seconds on an already-terminal call to wait for the recording_url.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "call_id": {
            "description": "The id returned by place_call.",
            "type": "string"
          },
          "wait_seconds": {
            "description": "0 (default) = instant status check. Up to 50 = server-side long-poll.",
            "maximum": 50,
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "call_id"
        ],
        "type": "object"
      },
      "annotations": {
        "title": "Get call",
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": false
      }
    },
    {
      "name": "list_calls",
      "description": "List the authenticated user's recent calls, newest first, with statuses and outcomes. Useful to recover a lost call_id or review call history.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "limit": {
            "description": "Max rows to return. Default 20.",
            "maximum": 100,
            "minimum": 1,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "annotations": {
        "title": "List calls",
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": false
      }
    },
    {
      "name": "set_call_visibility",
      "description": "Make a call owned by the authenticated user public or private. Calls are private by default. Only publish when the user explicitly asks: a public call exposes its objective, phone numbers, transcript, result and audio to anyone with its permanent, token-free listen_url, including live audio while in progress. Set is_public to false to disable token-free access again; existing private signed links remain valid until they expire. Public visitors cannot stop the call or change visibility.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "call_id": {
            "description": "The id of a call owned by this account.",
            "type": "string"
          },
          "is_public": {
            "description": "true publishes the call; false makes it private again.",
            "type": "boolean"
          }
        },
        "required": [
          "call_id",
          "is_public"
        ],
        "type": "object"
      },
      "annotations": {
        "title": "Set call visibility",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": true,
        "openWorldHint": true
      }
    },
    {
      "name": "end_call",
      "description": "End an in-progress call early. The voice agent wraps up politely (\"I'll let you go, thanks!\") and hangs up; the call is force-terminated if wrap-up takes more than ~10 seconds. Use when the user changes their mind or the call is no longer needed. The partial transcript and resolution are still produced.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "call_id": {
            "description": "The id returned by place_call.",
            "type": "string"
          }
        },
        "required": [
          "call_id"
        ],
        "type": "object"
      },
      "annotations": {
        "title": "End call",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": true,
        "openWorldHint": true
      }
    },
    {
      "name": "get_phone_number",
      "description": "Get the phone number connected to the authenticated user's account in E.164 format, along with its caller_id_status (verified or unverified). This is the user's own number used as outbound caller ID, not the service's SMS sending number. Takes no arguments and does not place a call or send a text.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {},
        "type": "object"
      },
      "annotations": {
        "title": "Get connected phone number",
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      }
    }
  ],
  "examples": {
    "estimate_call": {
      "arguments": {
        "to": "+12025550148"
      },
      "response": {
        "to": "+12025550148",
        "from": "+12025550100",
        "currency": "USD",
        "locale": "en-US",
        "language": "en",
        "one_minute_usage_percent": null
      }
    },
    "place_call": {
      "arguments": {
        "to": "+12025550148",
        "objective": "Ask whether order #482 has shipped and get the expected delivery date. Do not change the order or accept charges.",
        "context": "I am Sam at Acme; report missing information before making another call."
      },
      "response": {
        "call_id": "call_example",
        "status": "queued",
        "locale": "en-US",
        "language": "en"
      }
    },
    "get_call": {
      "arguments": {
        "call_id": "call_example",
        "wait_seconds": 50
      },
      "response": {
        "call_id": "call_example",
        "status": "completed",
        "recording_status": "processing",
        "recording_url": null,
        "resolution": {
          "outcome": "achieved",
          "summary": "Order #482 has shipped; delivery is expected Thursday.",
          "commitments": [],
          "follow_ups": [],
          "key_facts": [
            "Order #482 shipped"
          ],
          "callee_requested_no_further_calls": false
        }
      }
    },
    "list_calls": {
      "arguments": {
        "limit": 5
      },
      "response": {
        "user": {
          "name": "Sam",
          "phone": "+12025550100"
        },
        "calls": []
      }
    },
    "set_call_visibility": {
      "arguments": {
        "call_id": "call_example",
        "is_public": false
      },
      "response": {
        "call_id": "call_example",
        "is_public": false
      }
    },
    "end_call": {
      "arguments": {
        "call_id": "call_example"
      },
      "response": {
        "call_id": "call_example",
        "status": "canceled",
        "ended": true
      }
    },
    "get_phone_number": {
      "arguments": {},
      "response": {
        "phone_number": "+12025550100",
        "caller_id_status": "verified"
      }
    }
  },
  "exampleNotice": "Fictional request examples and response excerpts, not live account data or complete output schemas. Never dial the illustrative numbers."
}