Guide · phone numbers

How to Give an AI Agent a Phone Number

A phone number is not one thing. For an AI agent to use one, three pieces have to line up: a number the carrier routes to you, a voice runtime that answers and talks, and a control surface your agent can drive. This guide covers the three common ways to get all three, then walks through the CallMCP path tool call by tool call.

What "a phone number for an agent" actually means

Three ways builders do it

1. Wire the carrier yourself

Buy a number from a carrier, point its voice webhook at your server, and stream audio through your own speech-to-text, model and text-to-speech loop. You control everything, and you own everything: barge-in, latency, recording, retries, number porting, and compliance. This is the right call when the voice pipeline itself is your product.

2. Bind a number on a voice-agent platform

Voice-agent platforms bundle the runtime and let you attach a number to an assistant. The documented patterns are similar across vendors. Retell's docs describe buying a number and binding one agent for inbound and one for outbound calls (inbound_agent_id, outbound_agent_id). Vapi's docs describe importing a Twilio number with your Twilio credentials and attaching an assistant to it. Bland's API has an endpoint that purchases a number by area code, and Synthflow's docs cover buying a number, importing a SIP number, or bringing a Twilio one. In each case the platform is the agent: you configure prompts and voices in its dashboard or API.

3. Expose the phone as MCP tools

If you already have an agent (in Claude, in your own framework, in an automation tool), you may not want a second agent platform. The third option keeps your agent in charge and hands it phone capabilities as tools: search for a number, request it, attach it, place a call, read the transcript. That is what CallMCP does. A hosted voice agent answers and speaks on the line; your agent decides when to call, what the call is for, and what happens with the outcome.

The CallMCP path, step by step

Step 1: Sign up and get a number in the same response

The quickest number is the one signup gives you. The OTP flow on the homepage quickstart returns an api_key, an agent_id and a phone_number once you verify the emailed code. Many builders never need a second number. Read back what you hold with list_numbers:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_numbers", "arguments": {} }
}

Step 2: Put a reachable human on file first

Before searching for or buying another number, the server expects the owner's own phone on the business record. set_owner_phone saves it and, by default, turns on ring-first routing so calls try that phone before the AI agent picks up. If the owner won't give one, the tool takes declined: true instead, and you should not buy a number for that business afterward.

{
  "name": "set_owner_phone",
  "arguments": { "owner_phone": "+19085551234", "ring_first": true }
}

Step 3: Search live inventory

search_available_numbers queries the carrier in real time. All arguments are optional: area_code, country (two letters, default US) and limit (default 10, max 20).

{
  "name": "search_available_numbers",
  "arguments": { "area_code": "415", "country": "US", "limit": 5 }
}
// → { "success": true, "available_numbers": ["+14155550101", "+14155550118", ...] }

Step 4: Request the purchase, then wait for the owner

A number is billed by the carrier the moment it is bought, so buy_number is approval-gated. It stores a purchase request for the account owner to review while signed in. An agent cannot approve its own purchase: authority fields supplied by the caller, including human_confirmed, are recorded for attribution only. Your agent should relay the review link to the owner and must not say the number was bought while the request is pending. Pass dry_run: true to check scope and policy without creating a request.

{
  "name": "buy_number",
  "arguments": {
    "phone_number": "+14155550101",
    "reason": "Second line for the Oakland office",
    "idempotency_key": "buy-oakland-line-1"
  }
}
// → status: "pending_approval", plus a request_id and an approval object
//   with the review link to relay to the owner

Step 5: Attach it to an agent

A purchased number isn't routed until you attach it. attach_number takes the E.164 phone_number and an optional agent_id; leave the agent out to park the number in the business's pool. detach_number reverses it and is marked destructive, because it drops routing.

{
  "name": "attach_number",
  "arguments": { "phone_number": "+14155550101", "agent_id": "agt_9f2a1c" }
}

Step 6: Subscribe to events instead of polling

Register a webhook with set_webhook for call.received, call.completed, voicemail.received and phone_number.assigned. Deliveries are HMAC-SHA256 signed; the tool reference shows the header format and how to verify it.

What a number does not prove

The tool descriptions are blunt about this, and your agent should be too. A number showing up in list_numbers does not prove inbound calls reach the agent. A successful make_call does not prove inbound routing either. Read get_activation_status, which reports whether the owner's phone is on file and what the next setup action is, and then place a real inbound test call from another phone before telling anyone the line is live.

• Outbound calls need billing. make_call requires a plan with a card on file.
• Texting needs carrier registration. Business texting in the U.S. runs through carrier registration; get_text_registration reports the filing stage and the next question to ask the owner.
• Caller ID name is separate. set_branded_caller_id files the name landlines display (15 characters max, U.S. local numbers only). It is not showing just because the tool returned.
• Calling people has rules. Owning a number grants no permission to call anyone. Read outbound call safety and consent before your agent dials a number it didn't receive a call from.

Which option fits

Wire the carrier yourself if the voice pipeline is what you sell. Use a voice-agent platform if you want its dashboard to be the agent. Use MCP tools if the agent already exists and the phone is one more capability it should be able to use, with scopes, approvals and transcripts it can read. If you are weighing the control surfaces themselves, MCP vs REST for voice agents compares them on the same backend.