MCP clients
Hail exposes MCP as a remote server. Hail Cloud uses OAuth. Paste the URL into your client. Click Allow in the browser. Your agent then gets the call, SMS, email, agent, number and verification tools. There are no keys to manage and no installation.
For the easy onboarding path, refer to the client picker on hail.so/mcp. It has copy-paste setup for the 8 most common clients (Claude.ai, ChatGPT, Cursor, Gemini, …). This page is the technical reference behind those snippets.
URL
- Hail Cloud:
https://mcp.hail.so - Self-hosted:
http://<your-host>:8081— refer to Self-host below.
The Streamable HTTP transport serves the MCP root path. There is no /mcp suffix and no SSE.
For web-based clients (Claude.ai, ChatGPT), the URL must be reachable from the client's servers — public DNS + TLS. If you want web clients to reach a self-hosted instance, tunnel it via cloudflared / tailscale funnel.
Tools
Example. Ask your agent: "Find me a US number that can call and text." It calls quote_numbers with:
{ "country_code": "US", "capabilities": ["voice", "sms"] }The server exposes 43 tools. Schemas (args, validation, return shapes) are the source of truth — refer to mcp/hailhq/mcp/tools.py.
Every tool sets the MCP hints readOnlyHint, destructiveHint, idempotentHint and openWorldHint, so clients can ask for approval before a write. release_number, delete_agent, acquire_number, submit_verification, resubmit_verification and cancel_verification are marked destructive. The first three also need a confirmation argument (confirm_e164, confirm_name, confirm_total_cents). submit_verification and resubmit_verification need attest_authorized: true.
place_call, send_sms and send_email need recipient_consent set to the JSON boolean true. Strings such as "true" and numbers such as 1 are refused before any request is sent.
| Tool | Does |
|---|---|
place_call | Originate an outbound phone call. |
get_call | Fetch the current state and transcript of one call. |
list_calls | List recent calls (cursor-paginated). |
send_sms | Send an outbound SMS (recipient consent is required). |
get_sms | Fetch the current state of one SMS. |
list_sms | List recent SMS messages (cursor-paginated). |
send_email | Send an outbound email (supports attachment_ids). |
upload_email_attachment | Upload a small file (under about 50 KB) as base64, get back a reusable id. |
create_file_upload | A one-time link to upload a file with curl, for an email attachment or a verification document. |
get_email | Fetch one email's full record (body + inbound headers). |
list_emails | List emails (direction="inbound" for replies). |
get_email_raw | Presigned URL for an inbound email's raw MIME. |
get_email_attachment | Presigned URL for one inbound attachment. |
get_email_events | Page through one email's event history. |
get_email_stats | Aggregate email counts for a time window. |
get_events | Page through the event stream. |
list_email_domains | List sending identities + the default from address. |
whoami | Identify the human behind the session (for reply_to). |
list_contacts | List the org's contacts (members + manual contacts). |
lookup_contact | Find one contact by name, email, or phone fragment. |
create_contact | Add a manual contact. |
list_agents | List saved agents. |
get_agent | Fetch one saved agent. |
create_agent | Save an agent that answers calls and texts. |
update_agent | Change an agent. clear_fields removes optional values. |
delete_agent | Delete an agent. Destructive. Needs confirm_name. |
route_number | Choose which agent answers a number. |
route_email_domain | Choose which agent answers an email address, and who it answers. |
quote_numbers | Compare live carrier offers for a new number (read-only). |
list_number_regions | List the US/CA state codes quote_numbers takes as optional region (read-only). |
acquire_number | Buy a quoted number. Spends money. Needs confirm_total_cents. |
list_numbers | List the org's numbers (cursor-paginated). |
get_number | Fetch one number. |
release_number | Release a number. Destructive and permanent. Needs confirm_e164. |
get_verification_requirements | Read what a carrier needs to verify the org for a number type (read-only). |
check_verification | Run every check Hail can run on a verification form. Files nothing (read-only). |
check_verification_documents | Read the files of a verification form: values to fill it, and warnings. Uses daily document reads. |
submit_verification | Send details and documents to the carrier. Irreversible. Needs attest_authorized. |
list_verifications | List the org's verifications and their states (read-only). |
get_verification | Fetch one verification; poll it for approved (read-only). |
resubmit_verification | File a rejected number registration again from the kept answers and files, with fixes. Irreversible. Needs attest_authorized. |
cancel_verification | Cancel an awaiting_review one, dismiss a rejected one, or end an approved US SMS registration. |
confirm_verification | Enter the code the carrier texted a person (confirmation: "code"). |
Sending a file
A tool call carries text only, so a file in base64 makes the model write every character into the call. That is slow and fails for most real files. create_file_upload returns a one-time link instead, and the agent's shell sends the bytes:
-
create_file_upload:{"purpose": "email_attachment", "filename": "invoice.pdf", "content_type": "application/pdf"}. The result hasid,upload_url,expires_at(15 minutes) and a readycurlline. -
Replace
FILE_PATHin thecurlline with the file's absolute path and run it. Keep the single quotes, so a file name cannot run as a command; write any'in the path as'\''. For/home/agent/invoice.pdf:curl --silent --show-error --globoff --upload-file '/home/agent/invoice.pdf' \ 'https://api.hail.so/v1/uploads/<id>?token=<token>'The link needs no key and works once. The response has
size_bytesandsha256; compare them with the local file (wc -c,shasum -a 256). -
Use the
id: insend_email'sattachment_ids(email_attachment, 25 MB at most), or as{"slot", "upload_id"}in thefilesofcheck_verificationandsubmit_verification(verification_document: JPG, PNG or PDF, 10 MB at most, usable for 1 hour).
This needs a client with a shell (Claude Code, Codex, Cursor). Claude.ai web chat has none: there, only upload_email_attachment and base64 files work, for small files.
Getting a number over MCP
-
quote_numbers:{"country_code": "US", "capabilities": ["voice", "sms"]}. Offers listmonthly_cents,setup_centsandquote_id. Money is in cents. Quotes expire in 10 minutes. -
acquire_number: copyquote_id,country_codeandnumber_typefrom the offer. Setconfirm_total_centstomonthly_cents + setup_cents. For an offer withmonthly_cents: 115andsetup_cents: 50:{ "quote_id": "8b1f0c2e-0000-4000-8000-000000000001", "country_code": "US", "number_type": "local", "confirm_total_cents": 165 }The server checks the total. If it differs from the quote, the call fails with 409 and nothing is charged. The result is the number plus an
idempotency_key. To retry after a timeout, pass that key asidempotency_key. -
route_number:{"number_id": "<id>", "voice_agent_id": "<agent-id>"}.
Warning:
acquire_numberbuys a real number. It charges the setup fee and the first month now, then renews monthly. The account balance is the only spending limit. Keep the human approval prompt on for this tool.
Buying a number that needs verification
Some numbers, for example a UK mobile, need a carrier check of the organization first. quote_numbers marks those offers readiness: "verification_required". The whole flow works over MCP:
-
quote_numbers:{"country_code": "GB", "number_type": "mobile"}. The offer hasreadiness: "verification_required", itsquote_id, andsubject_types: who may verify for it (person,business, or both). -
Ask the user: "you or your company?". That is
subject_type(personorbusiness). It is required; never guess it. -
get_verification_requirements:{"country_code": "GB", "number_type": "mobile", "quote_id": "<quote_id>", "subject_type": "person"}. The result listsfields,documents(skip a slot whoseneeds_inputis false) andaddress_required. -
Ask the user for the files first, then for every field the files do not show. The agent must not invent or guess any value. The balance must cover the offer's
setup_centsplusmonthly_cents, orsubmit_verificationreturns a 402 error and sends nothing. Ask the user to add credit first. That amount is set aside while the carrier checks the papers. It pays for setup and the first month when the number is bought with this verification, and comes back if the verification is rejected or cancelled, or if no number is bought within 30 days of approval. Each entry in the offer'sverificationsshows it asheld_cents. -
Upload each file with
create_file_upload(see Sending a file):{"purpose": "verification_document", "filename": "passport.jpg", "content_type": "image/jpeg"}. Run thecurlline it returns. The upload id works for 1 hour. -
check_verification_documentswith the files and thedocuments(theoptionmay wait). An AI model reads each file. It returns the values the files show, by the form's own keys, andwarnings: an unreadable, upside-down or expired document, a file of another type than the chosen one, or a typed name that differs from the printed one. Confirm the values with the user and tell them each warning. A warning never blocks the submission. A workspace has 30 reads per day; after that a file comes backread: falsewithskipped: "daily_limit". Only the first 3 pages of a PDF are read, and a PDF of more than 5 pages is not read. -
check_verificationwith the same arguments assubmit_verification, minusattest_authorized. It runs every check Hail can run (credit, duplicates, required fields, documents, file types and sizes) and files nothing. Fix anyproblemswith the user. -
submit_verification. Eachfilesentry is{"slot", "upload_id"}, or{"slot", "content_type", "content_base64"}for a very small file. Slot names infilesmust be keys indocuments:{ "country_code": "GB", "number_type": "mobile", "quote_id": "<quote_id>", "subject_type": "person", "fields": { "first_name": "Ada", "last_name": "Lovelace" }, "address": { "customer_name": "Ada Lovelace", "street": "1 Example Road", "city": "London", "region": "London", "postal_code": "N1 1AA", "country_code": "GB" }, "documents": { "identity": { "option": "passport", "fields": {} } }, "files": [ { "slot": "identity", "upload_id": "<id from create_file_upload>" } ], "attest_authorized": true }The result holds the verification
idandstate, never the details. If the carrier finds a problem, the result listsproblems(loc,msg) and nothing is stored. Fix them with the user and submit again. A used upload is deleted once the verification is saved; after a failed submit it stays for the retry. -
get_verification:{"verification_id": "<id>"}. Poll every few minutes to hours, not every few seconds. Review takes business days. Hail sends no email or webhook when it ends. -
On
approved:quote_numbersagain. The offer is nowready. Thenacquire_numberandroute_numberas above. The organization may hold several approved verifications (several people or companies). Each entry in the offer'sverificationshas asubject_name: the person's or company's name from the form. When more than one is approved, show the user the names, ask which one, and pass itsidasverification_idtoacquire_number. -
On
rejected: readrejection_reasonand ask the user what to fix. For a number registration withresubmittable: true,get_sms_applicationshows the kept answers and file names, andresubmit_verificationfiles it again with only the changes (Hail keeps them for 30 days after submit, untilkept_until). Otherwise callcancel_verificationto dismiss it and submit a new one.
A person's US texting registration may wait on the person. confirmation: "code": ask them for the code the carrier texted and call confirm_verification with {"verification_id": "<id>", "code": "<code>"}. confirmation: "reply": they answer the carrier's text; nothing to call.
To register the organization to text US numbers from a US number, pass purpose: "sms" (default "number") with country_code: "US" and number_type: "local" to get_verification_requirements, submit_verification and list_verifications. Fees are charged from credit per step: when the details are submitted, when the carriers start their review, then monthly after approval (prices: the console and hail.so/pricing):
{
"country_code": "US",
"number_type": "local",
"subject_type": "business",
"purpose": "sms",
"fields": { "legal_name": "Acme Inc" },
"documents": {},
"files": [],
"attest_authorized": true
}Limits: JPG, PNG or PDF files, 10 MiB each, 29 MiB in total, at most 20 files and 20 fields. Compress photos to under about 7 MiB. Slot names use letters, digits, - and _ (at most 64). Each file must match its type. A second submission for the same country, number type, subject_type and name returns 409 while one exists.
A registration with waiting_for_credit: true files its campaign only once the credit covers the review fee. Its credit_needed_cents is its own share of the credit still needed, not a running total. The first waiting registration also carries any shortfall of the balance. So ask the user to add the sum of credit_needed_cents over the rows list_verifications returns with purpose: "sms". One top-up of that sum lets them all go at the next check. The number follows the balance, so read it again before the user pays.
Warning: The user's details, and any document sent as base64, pass through the model's context and are kept in the client's transcript. A document sent with an upload link does not. Keep the human approval prompt on for
submit_verification, and have the user hand over each value and file in the conversation. A submitted verification cannot be cancelled, and the carrier keeps the documents. Onlyawaiting_reviewandrejectedones can be cancelled, plus an approved US SMS registration.
Claude.ai (web)
- Settings → Connectors → Add custom connector
- Server URL:
https://mcp.hail.so - Save. Claude prompts you to authorize on first use. Click Allow in the browser tab that opens.
That is all. There is no API key field.
ChatGPT (web)
Custom MCP connectors are behind Developer Mode on ChatGPT today:
- Settings → Connectors → Advanced → Developer mode
- Create → paste
https://mcp.hail.so - Save. ChatGPT guides you through the OAuth consent on the first call.
Other clients
The client picker has setup snippets for Cursor, Gemini, Windsurf, Copilot, Zed, Raycast, and Claude Desktop. All follow the same shape: paste the URL, then click Allow.
Authorized apps
Each cloud client that you connect appears as a row at hail.so/console/apps. Revoke deletes the consent and every active access and refresh token for that client. The client's next tool call returns 401 and runs OAuth again from the start.
Access tokens last 30 days, and refresh tokens last 180 days. In practice, you authorize each client again approximately every six months. The consent screen opens, you click Allow, and the client continues.
Self-host
Self-hosted deployments do not use OAuth. Set HAIL_API_KEY and send it as a bearer token:
curl -H "Authorization: Bearer ${HAIL_API_KEY}" http://localhost:8081/The MCP service selects its auth mode from env at boot. For the full env-var contract, refer to the MCP modes table in the operations runbook (HAIL_AUTH_URL for cloud, HAIL_API_KEY for self-host, mutually exclusive).
Stdio
For hosts that require stdio, run the entry point in the self-hosted MCP container. From your Hail checkout:
docker compose run --rm -T mcp python -u -m hailhq.mcp.stdioThe container reads HAIL_API_KEY from .env and calls the API at http://api:8080.
HAIL_AUTH_URL must be empty in .env, not only in your shell: stdio reads .env and refuses to start when it is set.
Stdio uses the same tools as the HTTP service.
Hail documentation
Hail gives your AI agent a voice, a real phone number, and an email inbox — place AI phone calls with ElevenLabs voices, run an AI call center, send SMS and agent mail, all behind one MCP endpoint, one API key, one invoice. Most people use Hail Cloud; Hail's services are also self-hostable under AGPLv3, with LiveKit Cloud and channel providers remaining external.
Agents
An agent is a saved brain: instructions, greeting, AI line, voice, tools and limits. A number routes its incoming calls to one agent and its incoming texts to one agent. POST /calls can place outbound calls with the same agent.