Analyzes voice agent recordings to detect latency spikes, dead air, talk-overs, and say-do gaps for automated QA.
Also known as attenlabs/hotato
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- 295
- Latest version
- 1.9.0
- Last commit
- Aug 28, 2026
- License
- MIT
What is hotato MCP?
hotato analyzes voice agent recordings to detect latency spikes, dead air, talk-overs, and say-do gaps for automated QA.
Summary generated from the project's README
About hotato MCP server
Automating quality assurance for voice agents by detecting technical failures in call recordings is what hotato enables. It identifies specific issues such as latency spikes, dead air, talk-overs, and say-do gaps where an agent's actions do not match the conversation. The tool works locally on your machine using standard Python libraries, ensuring that audio files and traces remain on your disk without making external network calls.
Developers can use it with local audio files via the autopsy command or connect it to voice platforms like Vapi, Retell, Bland, Synthflow, and Millis. For Vapi and Retell, you provide an API key to pull recent call history and generate health reports. The system is designed to be integrated into CI/CD pipelines, where it can act as a gate by using the pin and prove commands to fail builds when specific bugs are detected in new agent versions.
What you can do with it
- 1Monitor platform healthCheck the recent history of calls from providers like Vapi to generate a stability report.
- 2Prevent regressions in CI/CDTurn a specific recorded bug into a permanent test that fails your build until the issue is resolved.
- 3Perform deep audio forensicsRun a detailed analysis on a single local audio file to generate a timestamped incident report.
Written from the project's README. Every use case is checked against a quote from it.
How to install hotato MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall hotato MCP in Claude Code
$ claude mcp add hotato -- uvx hotatoInstall hotato MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hotato": {
"command": "uvx",
"args": [
"hotato"
]
}
}
}Install hotato MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hotato": {
"type": "stdio",
"command": "uvx",
"args": [
"hotato"
]
}
}
}Install hotato MCP in VS Code CLI
$ code --add-mcp '{"name":"hotato","type":"stdio","command":"uvx","args":["hotato"]}'Install hotato MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hotato": {
"command": "uvx",
"args": [
"hotato"
]
}
}
}Install hotato MCP in Codex
$ codex mcp add hotato -- uvx hotatoInstall hotato MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hotato] command = "uvx" args = ["hotato"]
Install hotato MCP in Gemini CLI
$ gemini mcp add -s user hotato uvx -- hotatoInstall hotato MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hotato": {
"command": "uvx",
"args": [
"hotato"
]
}
}
}Configuration
RETELL_API_KEYVAPI_API_KEY
| Name | Description | |
|---|---|---|
| RETELL_API_KEY | — | |
| VAPI_API_KEY | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableattenlabs/hotato is public and reachablegithub.com/attenlabs/hotato ↗Pass
- Package names this repository as its sourcehotato names attenlabs/hotato as sourcepypi.org/project/hotato/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for hotatopypi.org/project/hotato/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-28github.com/attenlabs/hotato ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from hotatoPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubhotato
Find what broke in your agent calls. Pin it and CI stays red until you fix it.
pip install hotato
hotato check --demo # a bundled failing call: what broke, and when
hotato check ./call.wav # then your own recording
hotato vapi health # or your last 100 Vapi calls
Zero config. Vapi, Retell, Bland, Synthflow, Millis, or local audio. Works with any recording: mono, dual-channel, or a transcript. Timing math, not a judge. Offline. Free. MIT.
What it finds
- Say-do gaps: the caller interrupts to cancel (a barge-in), the agent says "canceled", the booking tool fires anyway. hotato takes the turn timing from the audio and the tool call from your OTel trace.
- Latency spikes: the pause before a reply going from 800 ms to over 2 s.
- Dead air: that pause reaching 5 s, or the line going quiet.
- Talk-over: the agent starts a fresh utterance over the caller.
Quickstart
Vapi
pip install hotato
export VAPI_API_KEY=...
hotato vapi health --last 7d --output report.html
Open report.html: every critical incident, timestamped, and your Voice Stability Score.
Retell
export RETELL_API_KEY=...
hotato retell health --call-id CALL_ID
--call-id is required and repeatable: you name the Retell calls to pull.
hotato bland health, hotato synthflow health, and hotato millis health
follow the Vapi shape. Those stacks mix both voices onto one channel, so
they measure silence timing, dead air and latency gaps, each finding with
its measured confidence; barge-in and talk-over need two channels.
Local audio
hotato autopsy ./call.wav
Writes a self-contained HTML report to hotato-output/, plus the JSON
pin reads. Open the HTML in your browser.
From finding a bug to gating on it
autopsy turns one recording into timestamped incidents. scan reads a
folder and tracks the trend. When you are ready, move a finding into CI:
hotato pin turns one incident into a portable failure check, and hotato prove re-runs every stored check and fails the build rather than pass on
evidence it cannot re-read. Every verdict carries its own evidence across
five dimensions: outcome, policy, conversation, speech, reliability.
A pinned check re-measures its own stored recording, so it holds the build
red on that bug and catches an edited bundle, a loosened policy, or an
engine upgrade that scores the same bytes differently. Clearing it takes a
fresh recording of the same moment against the current agent: hotato drive <bundle> places that call on Vapi or Twilio, and
docs/RECAPTURE.md is the walkthrough for every other
stack.
For continuous use: run hotato vapi health on a schedule, and open
hotato console --production-db evidence.db to watch calls land live.
Wire it into CI
The exit code is the verdict: 0 pass, 1 fail, 2 refuse (could not tell).
# .github/workflows/voice-qa.yml
on: [pull_request]
jobs:
hotato:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: attenlabs/hotato@v1.20.0
with:
contracts: contracts/
hotato-version: 1.20.0
contracts/ holds what pin wrote. Full workflow: docs/CI.md.
Point your agent at it
Point Claude Code, Cursor, or any coding agent at this repo: it reads
AGENTS.md and runs the loop end to end offline, no key. Over local
stdio the MCP server adds the scorer plus read/verify/propose tools:
uvx --from "hotato[mcp]" hotato-mcp (docs/MCP.md). Deploying is yours.
Nothing leaves your machine
hotato runs offline, on the machine that invokes it. The core is stdlib-only Python: no account, no key, no network call of its own. Your traces, prompts, and audio stay on your disk. Scoring with a language model you host yourself is a separate opt-in add-on, outside that core.
Go deeper
The whole loop, command by command: docs/LIFECYCLE.md.
First touch to a CI gate: docs/GETTING-STARTED.md.
Feed it what you already have: docs/CONNECT.md ·
docs/TRACE.md · docs/SIMULATE.md.
What every verdict stands on: docs/EVIDENCE-CONTRACT.md.
Next to the hosted alternatives: docs/COMPARE.md.
The deep toolkit -- capture, simulation, load, benchmarking, the fix ladder,
the fleet control plane -- lives under hotato lab (hotato lab --help).
The public commands are durable. hotato lab moves faster, and every
command name that worked before 1.17 still runs unchanged.
Specifications
| Property | Value |
|---|---|
| Footprint | ~10 MiB installed, 0 runtime dependencies (stdlib-only) |
| Reproducibility | byte-for-byte: the same recording, the same report |
| Exit codes | 0 pass · 1 fail · 2 refuse |
| Release integrity | OIDC Trusted Publishing + build-provenance attested |
| Runtime | offline, off the production data path |
PYTHONPATH=src python3 -m hotato.benchmark \
--scenarios corpus/real/scenarios --audio corpus/real/audio
On 13 recorded AMI Meeting Corpus clips, the median error between measured caller-onset and the human word-alignment label is 20 ms. Provenance: corpus/real/README.md · method: METHODOLOGY.md.
Timing is measurable only when the two voices arrive on separate channels; a mono or mixed export is marked NOT SCORABLE and refused (hotato trust --stereo call.wav). The full four-tier evidence policy (what each verdict stands on, per input) is docs/EVIDENCE-CONTRACT.md.
Contribute
Issues and PRs welcome: CONTRIBUTING.md · SECURITY.md · CHANGELOG · docs/
License
MIT (LICENSE)
mcp-name: io.github.attenlabs/hotato
hotato MCP questions
How do I add hotato MCP to Claude Code?
Run claude mcp add hotato -- uvx hotato in your terminal. Add --scope user to make it available in every project.
How do I add hotato MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can I use hotato with Vapi or Retell?
Yes, it supports Vapi, Retell, Bland, Synthflow, Millis, and local audio files.
How does hotato integrate with CI/CD pipelines?
It provides exit codes (0 for pass, 1 for fail, 2 for refuse) that can be used to gate pull requests in workflows like GitHub Actions.