Hail MCP server

Hail

Give your agent a real phone number and an email inbox — in minutes, not days.

Your agent needs to call a person to move an appointment. Hail connects to the telephone carrier and runs the voice pipeline — STT, TTS, turn detection. Your agent is the brain: point Hail at any OpenAI-compatible endpoint (bring your own LLM), or let Hail's fallback chain (OpenAI → Gemini → Anthropic) do the talking. SMS and email work the same way — one MCP endpoint, one API key, one invoice.

Self-hostable with Docker Compose; LiveKit Cloud and the communication providers remain external. Open source under AGPLv3.

Self-host quick start

Prerequisites: Git, Docker Engine, and Docker Compose v2. For a public production deployment you also need a domain, HTTPS, and a managed Postgres; start with the VM deployment guide.

The commands below run a local evaluation stack with bundled Postgres. Voice calls additionally require LiveKit Cloud, a carrier (Twilio, Telnyx or DIDWW), Deepgram, Cartesia, and at least one LLM provider. Email is optional and requires AWS SES.

git clone https://github.com/hail-hq/hail
cd hail
cp .env.example .env

# Generate a shared self-host key, then put it in .env as HAIL_API_KEY.
printf 'hk_%s\n' "$(openssl rand -base64 32 | tr -d '/+=' | head -c 40)"

# Edit .env and add the providers required for the channels you will use.
docker compose -f docker-compose.yml -f docker-compose.local.yml \
  run --rm api alembic upgrade head
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d
docker compose -f docker-compose.yml -f docker-compose.local.yml ps
curl --fail http://localhost:8080/healthz

Self-host authentication uses the HAILAPIKEY value from .env; it does not need an API-key row in Postgres. Export the same key and API URL in the shell where you use the CLI or SDK (Compose does not export .env into your shell):

export HAIL_API_URL=http://localhost:8080
export HAIL_API_KEY='<same value as .env>'

Next, follow LiveKit Cloud and Twilio (optionally Telnyx and DIDWW), then bind a phone number to the self-host organization using the first-run setup. To enable email, follow AWS SES.

Authentication differs by deployment:

• Hail Cloud (managed, at hail.so): run hail login. The device flow writes a key to ~/.hail/credentials.json.
• Self-host: do not run hail login; set HAILAPIURL and HAILAPIKEY as shown above, or pass --api-url and --api-key.

Full setup guides: self-hosting · Webhooks · MCP · operations

Install the CLI

On macOS or Linux with Homebrew:

brew install hail-hq/tap/hail
hail version

Homebrew adds the hail-hq/tap tap automatically. To update later:

brew upgrade hail-hq/tap/hail

Shortened. The full README is on GitHub.