MCP server

Built-in Model Context Protocol server. Any MCP-capable AI agent can drive your microphone and speak through your speakers.

Three tools

Transport

Unix domain socket at /tmp/voxctrl-mcp.sock (Linux) or named pipe \\.\pipe\voxctrl-mcp (Windows). Each connection is spawned as its own async tokio task. Newline-delimited JSON-RPC 2.0 — one JSON object per line, terminated with \n. Follows MCP spec 2024-11-05.

Enabling

Settings → General → MCP Server section → toggle Enable MCP Server. Or set directly in ~/.config/voxctrl/config.json under the mcp key:

{
  "mcp": {
    "server_enabled": true,
    "record_timeout": 15.0,
    "visual_feedback": true
  }
}

The server starts automatically when the app launches if server_enabled is true.

Claude Desktop

Add the bridge config to ~/.config/claude/claude_desktop_config.json manually — voxctrl must already be running before Claude Desktop connects. On Linux, the bridge uses socat to pipe stdio to the Unix socket:

{
  "mcpServers": {
    "voxctrl": {
      "command": "socat",
      "args": [
        "STDIO",
        "UNIX-CONNECT:/tmp/voxctrl-mcp.sock"
      ]
    }
  }
}

Protocol handshake

• Send initialize — receive protocolVersion 2024-11-05 and capability list
• Send notifications/initialized (no response expected)
• Send tools/list — receive the three tool definitions
• Call any tool with tools/call

Error codes

Behaviour notes

• While transcribe_voice records, the recording overlay is always shown — the user always has a visual indicator that the mic is live
• The mic is released automatically once VAD detects silence or timeout_seconds (default 15.0) elapses
• voxctrl's full post-processing pipeline (including OpenAI API LLM formatting/cleaning, if enabled) is applied before the transcript is returned
• If no speech is captured, transcribe_voice returns the literal text (no speech detected)
• speak_text returns as soon as the text is queued — does not block until playback finishes. If piper isn't installed or its voice files are missing, playback falls back to espeak-ng automatically
• get_status returns a JSON-encoded object as its text content: {"recording": false, "speaking": false}

Response loopback (FIFO)

For agents that generate responses to a named FIFO, set response_pipe on the target in targets.toml. voxctrl spawns an async run_fifo_responder task that watches the FIFO; when the agent writes a line to it, voxctrl reads it and pushes it straight to the TTS worker queue — no speak_text call required. The listener automatically handles agent disconnects (EOF) and reconnects on the next session without restarting voxctrl.

[[target]]
id = "my-agent"
label = "My Agent"
delivery = "pipe"
pipe_path = "/tmp/my-agent.in"
response_pipe = "/tmp/my-agent.out"   # agent writes responses here
append_newline = true