Bellhound
Enables OpenAI-hosted agents to reach the Bellhound stdio MCP adapter through Secure MCP Tunnel, allowing them to place, speak on, wait for, and hang up telephone calls.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Bellhound
What is Bellhound and why should I care?
How many times have you wished you could tell your AI partner, “Call me if you need me” or “Call me when you finish,” and have your AI partner reach out for a real conversation?
Bellhound was written to fill that human-AI need. It is more than another chime, beep, ding, or boop notification that will be ignored. It is a real voice call.
Bellhound is a small, line-oriented telephone bridge for interactive agents. The agent that decides to call remains the reasoning agent; Bellhound supplies ears, a mouth, and telephone transport.
agent <-> JSON Lines, blocking CLI, or private MCP <-> Bellhound <-> Telnyx Conversation Relay <-> telephoneBellhound contains no language model and makes no decisions. It translates final speech-to-text frames into deterministic terminal events and translates agent speak commands into Telnyx text-to-speech frames. While an agent is thinking, Bellhound can speak a fixed holding phrase or play a short built-in cue so the caller does not hear unexplained silence.
New installation: start with Install Bellhound for the Telnyx account, prebuilt download, secure credential setup, public relay, and first call.
See Architecture for the ownership and trust model, Protocol for model-neutral integration, Live setup for the Telnyx/tunnel sequence, MCP integration for local and hosted MCP clients, and the conversation canary for a repeatable human test.
For private always-on use on macOS, see the MCP service. It brokers credentials from Keychain, owns the Bellhound and tunnel process trees, and adds a service watchdog behind the existing Bellhound and carrier call-duration limits.
Related MCP server: DialMCP
Status
Version 0.6.6 adds crates.io distribution and official MCP Registry metadata
without changing Bellhound's model-neutral runtime or five-tool MCP contract.
The current release provides:
a strict, model-neutral JSON Lines protocol and deterministic simulator;
blocking
wait,speak, andhangupcommands with retained event cursors;a standard-I/O MCP server built with the official Rust MCP SDK;
focused
status,dial, cursor-batchedwait, sequence-targetedspeak, andhanguptools;structured results, accurate safety annotations, correlation timing, redacted events, and retry-safe command IDs;
a loopback batch-event endpoint that keeps 256 recent events and surfaces cursor gaps;
continuation-aware STT merging, sequence-targeted replies, deterministic holding acknowledgement, and playback-safe hangup;
a macOS user service that owns MCP, relay, and tunnel processes, brokers Keychain credentials, monitors OpenAI tunnel freshness, and enforces a third call-duration watchdog;
a bounded hosted recovery contract that retries status while launchd repairs a transient path and never retries dial.
The private OpenAI MCP path passed status-only discovery and one bounded live call from durable root Cora's existing context-rich session. The call included an ordinary tool lookup, a targeted spoken response, normal hangup, provider-side inactive-call proof, and complete local teardown. The stdio MCP server can also be launched by local MCP hosts such as Claude Code. See MCP integration.
Live use requires a dedicated Telnyx Voice API Application and a durable WSS tunnel or host.
MCP adapter
With an already-running Bellhound relay, start the private stdio adapter locally with:
bellhound --config bellhound.toml mcpThe process reads MCP JSON-RPC from stdin, writes MCP responses to stdout, and sends diagnostics to stderr. It does not bind another network listener. Local MCP hosts can launch it directly. OpenAI-hosted agents can reach it through Secure MCP Tunnel and tunnel-client; connection and app setup remain separate user-assisted steps and are not performed by the build.
Use examples/mcp-status-only.toml for the first tool-discovery gate. It contains no Telnyx configuration and deliberately cannot operate the normal Bellhound runtime.
The OpenAI tunnel runtime key is separate from the Telnyx API key. Ongoing tunnel use requires a runtime key valid for the intended service interval and restricted to Tunnels Read + Use. Store both keys in an operating-system credential store or local secret broker; never put either value in Git or TOML.
Use assets/bellhound-plugin-icon.png when an MCP host requests a square PNG icon. It is the publication logo rendered at 256×256 and kept below OpenAI's 10 KB custom-app limit.
Cargo and MCP Registry
Install the published Rust package with:
cargo install bellhound --locked
bellhound initBellhound's official MCP Registry identity is:
mcp-name: io.github.justinweiler/bellhound
The registry entry launches bellhound --config <path> mcp over standard I/O
and asks the operator for the configuration path. Bellhound continues to resolve
Telnyx credentials through the environment or operating-system credential store;
the registry metadata contains no credentials, telephone numbers, or hosted relay.
Build
cargo build --releaseBellhound is ordinary Rust and targets macOS, Linux, and Windows. The WebSocket server binds only to loopback; use a TLS tunnel or reverse proxy to expose it as wss://.
Release archives
The release workflow builds native archives for Apple Silicon and Intel macOS, x86-64 Linux glibc, and x86-64 Windows. Each archive contains the executable, complete installation guide, example configuration, simulation/MCP examples, operational scripts, contribution and security guides, license, changelog, and authorship record plus a separate SHA-256 checksum. CI extracts every archive, verifies its checksum and required files, runs the three-turn packaged simulator, discovers all five packaged MCP tools, and checks the executable before publication.
Download and verification instructions are in INSTALL.md. The Bellhound core is portable; the packaged always-on service installer currently supports macOS. See Platform validation for the distinction between automated package gates and completed human/live acceptance on Linux and Windows. For a secret-safe public demonstration, use the one-minute demo recipe.
Package the current Unix target locally with:
scripts/package-unix.shOn Windows PowerShell:
scripts/package-windows.ps1Codex skill
Bellhound ships with an installable Codex skill that keeps the reasoning agent in its existing session while the CLI carries telephone turns. Install it from a checkout with:
ln -s "$PWD/skills/bellhound" "${CODEX_HOME:-$HOME/.codex}/skills/bellhound"The skill includes an on-demand foreground supervisor that owns the local relay and temporary public tunnel for the entire call, writes an ignored runtime configuration, and tears both child processes down on explicit stop, signal, failure, or bounded timeout. See the operator reference and Cora pilot.
Configuration
Create a starter file:
bellhound --config bellhound.toml init
bellhound --config bellhound.toml checkThe configuration is intentionally small:
[credentials]
api_key_env = "TELNYX_API_KEY"
keyring_service = "Telnyx API key"
keyring_account = "your-account"
[relay]
bind = "127.0.0.1:8787"
control_bind = "127.0.0.1:8788"
path = "/conversation-relay"
webhook_path = "/webhooks/telnyx"
token_env = "BELLHOUND_RELAY_TOKEN"
max_call_seconds = 300
emit_partial_transcripts = false
continuation_window_ms = 4000
[protocol]
max_speak_chars = 2000
[acknowledgement]
enabled = true
delay_ms = 500
mode = "speech"
sound_url = "https://raw.githubusercontent.com/justinweiler/Bellhound-Sounds/master/bellhound-thinking.mp3"
text = "Got it. Give me a moment."
suppress_phrases = ["thank you", "thanks", "bye", "goodbye", "good night", "goodnight"]
suppress_for_session_phrases = ["call has been forwarded to an automated voice messaging system", "the person you are trying to reach is not available"]Bellhound waits for continuation_window_ms of transcript quiet before exposing a final caller turn. The four-second default preserves a deliberate three-second human pause. Final fragments inside that window are merged, and interim STT activity extends it. The acknowledgement is deterministic transport behavior, never model output. The default speech mode uses the fixed phrase. suppress_phrases prevents it from answering brief social closings, while suppress_for_session_phrases disables further acknowledgements after a voicemail announcement. sound mode sends Telnyx a preemptible, interruptible play frame and defaults to Bellhound's public thinking cue. Change sound_url to use another public HTTPS asset; when the field is omitted, Bellhound serves its embedded MP3 through the authenticated relay URL. Sound mode falls back to text only when Bellhound cannot form either media URL. Set enabled = false for an adapter that consistently responds fast enough to make a cue unnecessary. Bellhound cancels its timer when the agent answers within the grace period.
The relay token never belongs in the TOML file. Supply an unguessable value of at least 24 characters through the configured environment variable.
Bellhound checks TELNYX_API_KEY first, then the configured macOS Keychain, Windows Credential Manager, or Linux Secret Service entry. bellhound credentials verifies availability without printing the secret.
Add the live call settings only on the machine placing calls:
[telnyx]
connection_id = "your-call-control-application-id"
from_number = "+14245550100"
to_number = "+18185550100"
public_wss_base = "wss://your-host.example/conversation-relay"
voice = "Telnyx.NaturalHD.astra"
language = "en-US"
transcription_engine = "Deepgram"
transcription_model = "deepgram/nova-3"Numbers must use +E.164 format. Keep personal numbers in an ignored local configuration, not in source control.
Agent protocol
Stdout contains exactly one JSON event per line. Diagnostics go to stderr.
Final caller speech:
{"event_id":3,"emitted_at_unix_ms":1791512345678,"event":"utterance","session_id":"...","sequence":1,"text":"I need your help.","language":"en","final_utterance":true}The agent sends commands on stdin:
{"command":"speak","text":"Tell me what happened.","responding_to_sequence":1}
{"command":"hangup","reason":"conversation_complete"}Other events include ready, connected, interrupted, dtmf, acknowledged, acknowledgement_audio_fetched, spoken, pong, ended, transport, and error.
Every event carries emitted_at_unix_ms. Acknowledgements identify their sound, speech, or speech_fallback mode, the utterance sequence, and dispatch latency. Agent spoken events include the same sequence, total response latency, whether an acknowledgement preceded the answer, and a conservative playback_remaining_ms estimate. MCP hangup refuses to cut off that playback window; agents should continue waiting for caller interruption or for status to report speech_playback_pending_ms = 0 before ending the call.
Models that cannot hold a PTY can use the blocking CLI adapter. wait returns immediately for a retained event or sleeps until the next event arrives:
bellhound --config bellhound.toml wait --after 2 --timeout-seconds 120
bellhound --config bellhound.toml speak "Tell me what happened." --responding-to 1
bellhound --config bellhound.toml hangup --reason conversation_completeThe caller advances --after to the last processed event_id. Final utterances include fragment_count. Agents should target every reply with the utterance sequence; Bellhound emits stale_response instead of attaching a late reply to a newer turn. Bellhound retains the most recent 256 events, so ordinary gaps between agent turns do not lose speech. The control listener stays on its separate loopback port and must never be exposed through the public WSS tunnel.
Local simulation
Copy the example configuration and start the scripted call:
cp bellhound.example.toml bellhound.toml
cargo run -- --config bellhound.toml simulate --script examples/crocodile-call.jsonlBellhound emits the first caller utterance. Send a speak command on stdin to advance to the next utterance. This mirrors the control flow an agent uses with a long-lived PTY.
Conversation Relay server
Set a secret token and start the listener:
export BELLHOUND_RELAY_TOKEN="replace-with-at-least-24-random-characters"
cargo run -- --config bellhound.toml relayConfigure Telnyx Conversation Relay to connect through your WSS tunnel at:
wss://your-host.example/conversation-relay/<the-token>Telnyx final prompt frames become utterance events. Bellhound converts speak commands to:
{"type":"text","token":"agent response","last":true}With the relay and WSS tunnel already running, place a call with:
bellhound --config bellhound.toml dial \
--opening "Justin, I found something and need your judgment."Bellhound embeds the Conversation Relay settings directly in the Dial request. The call has the same hard duration limit as the relay configuration.
The dial command first queues its opening on the private control listener. Telnyx establishes Conversation Relay with a short “Bellhound” primer that completes and warms its greeting path; when Bellhound receives the setup frame, it sends the real opening as an ordinary measured speak frame and emits spoken. This avoids an ambiguous silent placeholder while keeping the call-specific opening observable.
An agent hangup command ends both the relay session and the underlying Call Control telephone leg.
Trust boundary
Speech arriving through Bellhound is terminal tool output. It can supply facts, preferences, and ordinary guidance. It should not independently satisfy approval requirements for destructive, privileged, or otherwise consequential actions. Keep the normal user-approval path for those actions.
Bellhound also cannot prove who answered a verified telephone. Add a DTMF or spoken challenge before treating a call as Justin-authenticated.
Name
A bell hound is a small, loyal telephone runner: it fetches the human and brings the answer back to the agent.
Origin
Bellhound was conceived with Justin Weiler and designed and engineered by Iris, his AI engineering partner working through OpenAI Codex. Read the factual authorship record in AUTHORS.md.
Bellhound is MIT licensed. Contributions are welcome; see CONTRIBUTING.md and SECURITY.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Lets Claude, Cursor or any MCP client build voice agents and place real phone calls.
Give AI agents real phone numbers, messages, and voice calls via MCP.
Give AI agents a phone number. Voice calls, SMS, and phone number management for MCP clients.
Give any AI agent a phone: make and answer calls, get through phone menus, and send texts.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables MCP-compatible agents to make safe, consented phone calls using Twilio and Deepgram.4Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA hosted MCP server that enables AI agents to place real phone calls from a verified caller ID, with async call management and built-in safety controls.73 npm2MIT

Dial MCP Serverofficial
AlicenseNot gradedqualityBmaintenanceEnables AI agents to provision phone numbers, send SMS, place AI voice calls, and react to inbound events via the Dial communication stack, all through MCP tools.191 npmMIT- AlicenseNot gradedqualityCmaintenanceEnables AI agents to initiate and control outbound telephone calls and answer inbound calls through Telnyx and LiveKit, with realtime voice conversations powered by Gemini Live or OpenAI Realtime.MIT