Hail

Phone, SMS & email for AI agents — one remote MCP endpoint, OAuth login, zero install.

CommunityDegradedNo sign-inGlobalFreeRead-only

What it can do

    What data it sees

    Do you need an account

    No: the server works without sign-in

    Phone, SMS & email for AI agents — one remote MCP endpoint, OAuth login, zero install.

    How to connect

    How to connect Hail to Claude

    The server address to paste into Claude settings:

    https://mcp.hail.so

    1. Open Claude (claude.ai or the desktop app).
    2. Go to Settings → Connectors.
    3. Click Add custom connector.
    4. Paste the server address copied below into Remote MCP server URL and click Add.
    5. In a chat, click + → Connectors and switch the new connector on.

    Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

    Authorization

    After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

    How to connect Hail to ChatGPT

    The server address to paste into ChatGPT settings:

    https://mcp.hail.so

    1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
    2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
    3. Open Settings → Connectors and click Create.
    4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
    5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
    6. In a new chat open + → Apps/Connectors and enable the connector.

    OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

    Authorization

    On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

    How to connect Hail to Cursor

    The server address to paste into Cursor settings:

    https://mcp.hail.so

    Fastest: click Open in Cursor below and confirm the prompt.

    Manually:

    1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
    2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
    3. Save the file. The server appears in the MCP list; authorize it there if asked.

    Authorization

    If the service needs sign-in, an authorize button appears next to the server in the MCP list.

    Server tool list (20)

    Raw names from tools/list. Only developers need these.

    place_callOriginate an outbound phone call. Provide ``system_prompt`` (mode A — Hail's bundled fallback LLM uses this prompt) or ``llm`` (mode B — bring your own OpenAI-compatible endpoint as ``{"base_url": ..., "api_key": ..., "model": ...}``), or both. At least one is required. Passing both runs your prompt on your own endpoint: it receives Hail's voice preamble plus your prompt as the leading system message. ``to`` must be E.164 (e.g. ``+14155551234``). ``from_`` is optional and defaults to the first active number on your org. ``first_message`` is spoken verbatim on pickup; omit it to let the agent open the conversation itself — it reacts to how the call was answered, or introduces itself after silence. ``language`` sets the call's spoken language for speech-to-text, text-to-speech, and turn detection, as a lowercase ISO 639-1 code (e.g. ``"da"``); 39 languages are supported (server rejects others with 422); omit for English. STT provider selection is console-BYO-only (no per-call override); configure it on the organization to pin a provider. ``ai_disclosure=False`` skips the spoken "this is an AI assistant" line at the start of the call. Leave enabled unless the user has verified it is not required for this call — US artificial-voice calls (47 CFR 64.1200(b)(1)) and several AI bot-disclosure laws require it, and Hail does not verify this. The agent still identifies itself as an AI if asked. ``metadata`` is free-form JSON attached to the call record. ``tools`` are the agent tools to allow on this call. Omit for all available; pass ``[]`` to disable. ``recipient_consent`` is required: attest that you (the caller triggering this request) have obtained the lawful consent needed to contact this recipient. The API rejects the request (422)
    send_emailSend an outbound email through your configured SES sender. ``to`` is a non-empty list of RFC-style email addresses. At least one of ``body_text`` / ``body_html`` is required (both is fine — multipart-alternative). Prefer including ``body_html``: open and click tracking only works for emails with an HTML body. A plain-text-only email still gets sent, delivered, and bounce events, but opens and clicks are never tracked. ``cc``, ``bcc``, and ``reply_to`` are optional and follow the usual mail conventions. Hail sets no ``reply_to`` of its own — to have replies reach the human running this session, call ``whoami`` and pass their ``email``. ``recipient_consent`` is required: attest that you (the caller triggering this request) have obtained the lawful consent needed to email this recipient. The API rejects the request (422) if this is not ``true`` — Hail does not verify consent for you. Set ``message_type="marketing"`` for promotional email (this additionally requires a non-empty ``consent_source`` describing how/where consent was obtained) — leave as the default ``"informational"`` for transactional/service email. ``from_`` is optional only while the workspace has one verified sender identity. With several, omitting it returns 422 listing them — call ``list_email_domains`` and pass one. With none, the server auto-mints a per-org hail-mail address of the form ``<user>+<org>@<base>`` if the operator configured ``HAIL_MAIL_BASE_DOMAIN`` (the ``<org>`` part is derived from your organization id; the ``<user>`` part comes from ``HAIL_MAIL_FROM`` / ``HAIL_MAIL_DEFAULT_USER_PREFIX``, or an explicit row created via ``POST /email-domains``). When supplied, ``from_`` must match a verified row already in ``email_domains`` (register one with the
    upload_email_attachmentUpload a file to attach to a future outbound email. ``content_base64`` is the file's raw bytes, base64-encoded. Returns ``{"id": ..., "filename": ..., "content_type": ..., "size_bytes": ...}`` — pass ``id`` in ``send_email``'s ``attachment_ids`` list. The id is reusable across many sends and expires in 24h if never used. Files over 25MB (combined with the message body and any other attachments, per send) are rejected — host large files externally and link to them in the body instead.
    get_callFetch the current state of one call by id. Use this after ``place_call`` (or to check on any prior call) to read the call's latest ``status`` and timing fields. Returns the API's ``CallResponse`` as a dict, or ``{"error": "call not found"}`` for an unknown id.
    list_callsList recent calls in your organization, newest first. Cursor-paginated: pass the previous response's ``next_cursor`` to fetch the next page. ``status`` (one of queued, dialing, ringing, in_progress, completed, failed, busy, no_answer, canceled) and ``to`` (E.164) are optional server-side filters. Returns a dict ``{"items": [...], "next_cursor": <str|None>}``.
    send_smsSend an outbound SMS from your organization's dedicated number. ``to`` must be E.164 (e.g. ``+14155551234``). ``body`` is the message text. SMS requires a dedicated phone number on your organization — it does not use the shared voice-call pool. ``recipient_consent`` is required: attest that you (the caller triggering this request) have obtained the lawful consent needed to text this recipient. The API rejects the request (422) if this is not ``true`` — Hail does not verify consent for you. Set ``message_type="marketing"`` for promotional texts (this additionally requires a non-empty ``consent_source``) — leave as the default ``"informational"`` for transactional/service texts. ``idempotency_key`` defaults to a fresh UUID and is returned in the response under ``idempotency_key`` — pass the same value on a retry to replay rather than re-send. Example: send_sms(to="+14155551234", body="Your order shipped!", recipient_consent=True) Returns the ``SmsResponse`` dict (id, status, from_e164, to_e164, segment_count, ...). On failure returns ``{"error": "<message>"}`` instead.
    get_smsFetch the current state of one SMS by id. Use this after ``send_sms`` to check delivery status. Example: get_sms(sms_id="...")
    list_smsPage through recent SMS messages for your organization. ``status`` filters to one of: queued, sent, delivered, failed, undelivered, received. ``to`` filters to messages sent to a specific E.164 number. Paginate with the returned ``next_cursor``.
    get_emailFetch the full record of one email by id. Returns the complete row — including ``body_text`` / ``body_html`` and (for inbound mail) the ``in_reply_to`` / ``message_id`` headers and ``spam``/``virus``/``spf``/``dkim``/``dmarc`` verdicts. Use this after ``list_emails`` to read a received reply's body. Returns the API's ``EmailResponse`` as a dict, or ``{"error": "resource not found"}`` for an unknown id.
    list_emailsList emails in your organization, newest first. Cursor-paginated: pass the previous response's ``next_cursor`` to fetch the next page. Two optional server-side filters: * ``direction`` — ``outbound`` or ``inbound``. Pass ``direction="inbound"`` to read replies and other received mail. * ``status`` — one of ``queued``, ``sent``, ``failed``, ``bounced``, ``complained``, ``received``. Items are trimmed summaries (no message body). Call ``get_email`` with an item's ``id`` to read the full body. Example: list_emails(direction="inbound") Returns ``{"items": [...], "next_cursor": <str|None>}`` on success, or ``{"error": "<message>"}`` instead.
    get_email_rawGet a fetchable URL for an email's original MIME source. Returns ``{"url": "<presigned-s3-url>"}`` — a short-lived (~5 minute) link to the full raw RFC822 message. Fetch the URL directly to read the complete original; it needs no auth header. Raw source exists for **inbound** mail only — outbound ids return ``{"error": "resource not found"}``.
    get_email_attachmentGet a fetchable URL for one inbound email attachment. ``attachment_id`` comes from an item in ``get_email``'s ``attachments`` list. Returns ``{"url": "<presigned-s3-url>"}`` — a short-lived (~5 minute) link to the attachment bytes, fetchable directly with no auth header. Unknown ids return ``{"error": "resource not found"}``.
    get_email_eventsDelivery/engagement timeline (sent→delivered→opened…) for one email. Chronological lifecycle events for a single email — use this to see exactly what happened to one message (bounced? opened? clicked?) rather than the account-wide aggregates ``get_email_stats`` returns. Returns ``{"items": [...], "next_cursor": ...}`` where each item has ``kind`` (one of sent, delivered, delivery_delayed, bounced, complained, rejected, opened, clicked), ``payload``, and ``occurred_at``. ``opened`` and ``clicked`` only occur for emails sent with an HTML body. A plain-text-only email still gets sent, delivered, and bounce events, but opens and clicks are never tracked. Pass ``cursor`` from a previous ``next_cursor`` to page (``limit`` 1..1000, default 100). On failure returns ``{"error": "resource not found"}`` for an unknown id.
    get_email_statsAccount-level email deliverability stats (counts, rates, time series). Aggregates across your whole organization's outbound mail over a window — use this for "how's deliverability doing" rather than one message's history (``get_email_events`` covers that). ``from_`` / ``to`` are ISO 8601 timestamps (defaults: last 7 days ending now). ``bucket`` is ``"day"`` (default) or ``"hour"`` — ``"hour"`` is limited to an 8-day span; any range is capped at 92 days. Returns ``{"from": ..., "to": ..., "bucket": ..., "totals": {...}, "rates": {...}, "series": [...]}`` — ``totals``/each ``series`` bucket carry counts (sent, delivered, bounced, opened, ...) and ``rates`` carries derived ratios (delivery, bounce, open, click), each ``None`` when ``totals.sent`` is 0. Open and click numbers only count HTML emails. Plain-text-only emails are never tracked for opens or clicks, so they lower those rates. On failure returns ``{"error": "<message>"}`` instead.
    get_eventsPage through events from across the org or one resource. Pass ``id="<type>:<uuid>"`` to narrow to a single resource — supported types are ``call``, ``email``, and ``sms`` (e.g. ``id="sms:<uuid>"`` after ``send_sms``). When narrowed to a call, the response includes a ``call_status`` field reflecting the call's current state. Without ``id``, returns events from across the whole org. ``kind`` filters server-side by event kind (``state_change``, ``agent_turn``, ``user_turn``, ``tool_call``, ``error``, ...). This is **not** a streaming subscription — the call returns whatever events exist now plus a ``next_cursor`` if more pages remain. To follow a call to completion, loop: pass the previous response's ``next_cursor`` until ``next_cursor`` is null and, when narrowed to a call, ``call_status`` is one of ``completed``, ``failed``, ``busy``, ``no_answer``, ``canceled`` (the terminal set). Example: get_events(id="call:0c2f...-...", limit=200) Returns ``{"items": [...], "next_cursor": <str|None>, "call_status": <str|None>}`` on success, or ``{"error": ...}`` on a malformed ``id`` or upstream failure.
    list_contactsList the workspace's contacts: org members (with their phone/email) plus manually saved contacts. Use ``lookup_contact`` for name searches. ``q`` optionally filters server-side (matches name/email/phone). ``limit`` caps the page (server default 100, max 500). Returns ``{"items": [{"id", "kind", "name", "phone_e164", "email", "role"}, ...]}`` — ``kind`` is ``"member"`` (id ``member:<user_id>``, ``role`` set) or ``"manual"`` (id is the contact's UUID, ``role`` null).
    lookup_contactFind a contact by name, email, or phone fragment. Resolve a person to their ``phone_e164``/``email`` BEFORE calling ``place_call``, ``send_sms``, or ``send_email`` — do not guess a contact's number. Returns up to 10 matches, same item shape as ``list_contacts``. Example: lookup_contact(query="maya")
    list_email_domainsList the addresses this workspace can send email from. Call this BEFORE ``send_email`` when you do not already know the ``from_`` address — do not guess a domain. Returns ``{"items": [...], "next_cursor": ..., "default_from": ...}``. Each item carries ``domain``, ``kind`` (``"custom"`` or ``"hail_mail"``) and ``verification_status``; only ``"verified"`` rows can send. A ``custom`` item's ``domain`` is a bare DNS name that accepts any local-part (``sales@acme.com``); a ``hail_mail`` item's ``domain`` is already a full address. ``default_from`` is the address a ``send_email`` with no ``from_`` goes out as. It is null when the workspace has several verified identities — then ``send_email`` rejects a missing ``from_`` and you must pass one from ``items``. Example: list_email_domains()
    whoamiIdentify the human whose credentials this session runs under. Use it to sign or route mail as that person: pass their address as ``send_email(reply_to=...)`` so replies reach them rather than the sending domain, which is often an unattended ``noreply@``. Returns ``{"auth_kind", "organization_id", "user_id", "email", "name"}``. ``user_id``/``email``/``name`` are null when the server runs on a shared operator key (``auth_kind="shared"``) — there is no human behind it, so send without a ``reply_to``. Example: whoami()
    create_contactSave a new contact for the workspace. Provide at least one of ``phone_e164`` (E.164, e.g. ``+14155551234``) or ``email`` — the API rejects (422) a contact with neither. A duplicate phone or email on an existing contact returns 409. Example: create_contact(name="Maya Chen", phone_e164="+14155551234") Returns the created contact entry as a dict. On failure returns ``{"error": "<message>"}`` instead.