documentation

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.

ToolDoes
place_callOriginate an outbound phone call.
get_callFetch the current state and transcript of one call.
list_callsList recent calls (cursor-paginated).
send_smsSend an outbound SMS (recipient consent is required).
get_smsFetch the current state of one SMS.
list_smsList recent SMS messages (cursor-paginated).
send_emailSend an outbound email (supports attachment_ids).
upload_email_attachmentUpload a small file (under about 50 KB) as base64, get back a reusable id.
create_file_uploadA one-time link to upload a file with curl, for an email attachment or a verification document.
get_emailFetch one email's full record (body + inbound headers).
list_emailsList emails (direction="inbound" for replies).
get_email_rawPresigned URL for an inbound email's raw MIME.
get_email_attachmentPresigned URL for one inbound attachment.
get_email_eventsPage through one email's event history.
get_email_statsAggregate email counts for a time window.
get_eventsPage through the event stream.
list_email_domainsList sending identities + the default from address.
whoamiIdentify the human behind the session (for reply_to).
list_contactsList the org's contacts (members + manual contacts).
lookup_contactFind one contact by name, email, or phone fragment.
create_contactAdd a manual contact.
list_agentsList saved agents.
get_agentFetch one saved agent.
create_agentSave an agent that answers calls and texts.
update_agentChange an agent. clear_fields removes optional values.
delete_agentDelete an agent. Destructive. Needs confirm_name.
route_numberChoose which agent answers a number.
route_email_domainChoose which agent answers an email address, and who it answers.
quote_numbersCompare live carrier offers for a new number (read-only).
list_number_regionsList the US/CA state codes quote_numbers takes as optional region (read-only).
acquire_numberBuy a quoted number. Spends money. Needs confirm_total_cents.
list_numbersList the org's numbers (cursor-paginated).
get_numberFetch one number.
release_numberRelease a number. Destructive and permanent. Needs confirm_e164.
get_verification_requirementsRead what a carrier needs to verify the org for a number type (read-only).
check_verificationRun every check Hail can run on a verification form. Files nothing (read-only).
check_verification_documentsRead the files of a verification form: values to fill it, and warnings. Uses daily document reads.
submit_verificationSend details and documents to the carrier. Irreversible. Needs attest_authorized.
list_verificationsList the org's verifications and their states (read-only).
get_verificationFetch one verification; poll it for approved (read-only).
resubmit_verificationFile a rejected number registration again from the kept answers and files, with fixes. Irreversible. Needs attest_authorized.
cancel_verificationCancel an awaiting_review one, dismiss a rejected one, or end an approved US SMS registration.
confirm_verificationEnter 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:

  1. create_file_upload: {"purpose": "email_attachment", "filename": "invoice.pdf", "content_type": "application/pdf"}. The result has id, upload_url, expires_at (15 minutes) and a ready curl line.

  2. Replace FILE_PATH in the curl line 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_bytes and sha256; compare them with the local file (wc -c, shasum -a 256).

  3. Use the id: in send_email's attachment_ids (email_attachment, 25 MB at most), or as {"slot", "upload_id"} in the files of check_verification and submit_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

  1. quote_numbers: {"country_code": "US", "capabilities": ["voice", "sms"]}. Offers list monthly_cents, setup_cents and quote_id. Money is in cents. Quotes expire in 10 minutes.

  2. acquire_number: copy quote_id, country_code and number_type from the offer. Set confirm_total_cents to monthly_cents + setup_cents. For an offer with monthly_cents: 115 and setup_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 as idempotency_key.

  3. route_number: {"number_id": "<id>", "voice_agent_id": "<agent-id>"}.

Warning: acquire_number buys 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:

  1. quote_numbers: {"country_code": "GB", "number_type": "mobile"}. The offer has readiness: "verification_required", its quote_id, and subject_types: who may verify for it (person, business, or both).

  2. Ask the user: "you or your company?". That is subject_type (person or business). It is required; never guess it.

  3. get_verification_requirements: {"country_code": "GB", "number_type": "mobile", "quote_id": "<quote_id>", "subject_type": "person"}. The result lists fields, documents (skip a slot whose needs_input is false) and address_required.

  4. 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_cents plus monthly_cents, or submit_verification returns 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's verifications shows it as held_cents.

  5. Upload each file with create_file_upload (see Sending a file): {"purpose": "verification_document", "filename": "passport.jpg", "content_type": "image/jpeg"}. Run the curl line it returns. The upload id works for 1 hour.

  6. check_verification_documents with the files and the documents (the option may wait). An AI model reads each file. It returns the values the files show, by the form's own keys, and warnings: 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 back read: false with skipped: "daily_limit". Only the first 3 pages of a PDF are read, and a PDF of more than 5 pages is not read.

  7. check_verification with the same arguments as submit_verification, minus attest_authorized. It runs every check Hail can run (credit, duplicates, required fields, documents, file types and sizes) and files nothing. Fix any problems with the user.

  8. submit_verification. Each files entry is {"slot", "upload_id"}, or {"slot", "content_type", "content_base64"} for a very small file. Slot names in files must be keys in documents:

    {
      "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 id and state, never the details. If the carrier finds a problem, the result lists problems (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.

  9. 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.

  10. On approved: quote_numbers again. The offer is now ready. Then acquire_number and route_number as above. The organization may hold several approved verifications (several people or companies). Each entry in the offer's verifications has a subject_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 its id as verification_id to acquire_number.

  11. On rejected: read rejection_reason and ask the user what to fix. For a number registration with resubmittable: true, get_sms_application shows the kept answers and file names, and resubmit_verification files it again with only the changes (Hail keeps them for 30 days after submit, until kept_until). Otherwise call cancel_verification to 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. Only awaiting_review and rejected ones can be cancelled, plus an approved US SMS registration.

Claude.ai (web)

  1. Settings → Connectors → Add custom connector
  2. Server URL: https://mcp.hail.so
  3. 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:

  1. Settings → Connectors → Advanced → Developer mode
  2. Create → paste https://mcp.hail.so
  3. 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.stdio

The 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.

On this page