three.ws Herald — Claude Code MCP server: what it does, how to install
Spawns a 3D companion inside your browser tab to announce agent task completion or urgent failures out loud. Keeps key alerts noticeable.
claude mcp add --env THREE_WS_API_KEY=<THREE_WS_API_KEY> --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> --transport stdio herald-mcp -- npx -y @three-ws/herald-mcpWhat three.ws Herald does
The server sends priority alerts from your agent directly to your personal channel on three.ws. Instead of letting critical updates vanish inside terminal scrollback, an animated avatar steps into your open browser tab, gestures, speaks the message, and provides an optional link. If your hardware lacks a GPU, it falls back to a readable interface card.
It supplies three tools. The announce tool handles custom notices with urgency scored from 0 to 100, announce_result summarizes finished runs, and check_rail tests connectivity quietly. The browser client drops routine spam automatically through importance gates, deduplication, and quiet-hour settings.
If no tab stays open to receive the broadcast, the message expires in five minutes. Running this requires a valid THREE_WS_API_KEY scoped to herald:announce. Broadcasts target solely the key holder, which prevents accidental notifications to other teammates.
What it helps with
- get spoken alerts whenever prolonged background tasks complete
- catch broken scripts or failing workers without staring at logs
- prompt human intervention when the agent requires quick decisions
- verify notification rail wiring safely with zero-importance tests
Example prompts for the agent
- Run the database migration and notify me through herald when done
- Verify the herald notification pipeline connection
- If the build fails, send a high-urgency herald broadcast with the dashboard link
How to install three.ws Herald
Platform CLI
claude mcp add --env THREE_WS_API_KEY=<THREE_WS_API_KEY> --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> --transport stdio herald-mcp -- npx -y @three-ws/herald-mcpReplace <…> with your own values
Platform CLI
codex mcp add herald-mcp --env THREE_WS_API_KEY=<THREE_WS_API_KEY> --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> -- npx -y @three-ws/herald-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"herald-mcp": {
"command": "npx",
"args": [
"-y",
"@three-ws/herald-mcp"
],
"env": {
"THREE_WS_API_KEY": "<THREE_WS_API_KEY>",
"THREE_WS_BASE": "<THREE_WS_BASE>",
"THREE_WS_TIMEOUT_MS": "<THREE_WS_TIMEOUT_MS>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"herald-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@three-ws/herald-mcp"
],
"env": {
"THREE_WS_API_KEY": "<THREE_WS_API_KEY>",
"THREE_WS_BASE": "<THREE_WS_BASE>",
"THREE_WS_TIMEOUT_MS": "<THREE_WS_TIMEOUT_MS>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e THREE_WS_API_KEY=<THREE_WS_API_KEY> -e THREE_WS_BASE=<THREE_WS_BASE> -e THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> herald-mcp npx -y @three-ws/herald-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about three.ws Herald
How to install three.ws Herald in Claude Code?
Run claude mcp add herald-mcp -e THREE_WS_API_KEY=<THREE_WS_API_KEY> -- npx -y @three-ws/herald-mcp using your generated key.
What does three.ws Herald do?
It surfaces urgent notices from CLI agents into your browser using voice and an animated 3D character. This prevents crucial task endings or crashes from getting lost in terminal logs.
Can this server send messages to other team members?
No, all broadcasts route exclusively to live sessions belonging to the token owner. The tools have no recipient argument to guard against spam or token abuse.
