prodius-mcp

Let your AI agents reach you by voice.

prodius-mcp is a lightweight MCP server that bridges any MCP-capable AI tool (Claude Code, Cursor, Windsurf, Codex CLI, and more) to the Prodius desktop app. When an agent needs your input, a popup appears on your screen — wherever you are — and you answer by voice. No switching back to the terminal.

It's a thin stdio shim: standard library only, no third-party dependencies, fast startup, and it talks only to the Prodius desktop app running locally on 127.0.0.1.

This package needs the Prodius desktop app. On its own it does nothing: the popup, the voice capture and the transcription all happen in the desktop app. Get it at prodius.ai/download.

Requirements

• Python 3.10+

• The Prodius desktop app installed and running, with Voice Bridge enabled in settings.

Related MCP server: hermes-mcp-bridge

Install

Published on PyPI as prodius-mcp:

pip install prodius-mcp

If prodius-mcp isn't found afterwards, make sure the Python environment you installed into is on your PATH — or use pipx install prodius-mcp.

Connect your tool

Claude Code

The quickest start is one command:

claude mcp add prodius -- prodius-mcp

For the full experience (correct agent label in the modal header, automatic conversation reset on /clear), add the block below to your ~/.claude/settings.json instead. The claude mcp add shortcut omits both pieces.

{
  "env": { "PRODIUS_AGENT_NAME": "Claude Code" },
  "mcpServers": {
    "prodius": {
      "command": "prodius-mcp",
      "args": [],
      "env": { "PRODIUS_AGENT_NAME": "Claude Code" }
    }
  },
  "hooks": {
    "SessionStart": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "prodius-mcp-reset" }] }
    ]
  }
}

The SessionStart hook calls prodius-mcp-reset whenever you run /clear or open a new session so Prodius doesn't carry stale context across conversations. It leaves the conversation alone when a session is resumed, compacted or forked. The top-level env makes the agent name visible to that hook.

To enable voice push (microphone stays available between questions so you can speak to Claude anytime, not just when it asks), start Claude with the channels flag:

claude --dangerously-load-development-channels server:prodius

Cursor / Windsurf / any MCP client

Add to your client's MCP config (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "prodius": { "command": "prodius-mcp" }
  }
}

Codex CLI

[mcp_servers.prodius]
command = "prodius-mcp"
env = { PRODIUS_AGENT_NAME = "Codex CLI" }

Full setup instructions for each tool, including session-reset hooks and optional voice push, live at prodius.ai/connect.

Tools exposed

How often the agent reaches out is your call, not the server's. Without instructions it only contacts you when it is blocked (an approval or a decision). Tell it otherwise in your CLAUDE.md / AGENTS.md; presets are at prodius.ai/connect.

Sub-agents must not call either tool. They return their results to the parent agent; only the top-level agent talks to you through Prodius. The server advertises this in its instructions, but it is worth repeating in your own CLAUDE.md.

How it works

your AI tool  ──stdio (JSON-RPC)──▶  prodius-mcp  ──HTTP──▶  Prodius desktop app
                                       (this pkg)              (overlay + voice)

prodius-mcp is a stdio shim and nothing more. It speaks MCP over stdin/stdout to your AI tool and forwards each call to the Prodius desktop app's local Voice Bridge — a set of /mcp/* HTTP routes on 127.0.0.1, authenticated with a Bearer token that the desktop app generates on first run. The overlay rendering, the voice pipeline, and the routing of answers back to the right agent all live in the desktop app.

Consequences worth knowing:

• Nothing leaves your machine via this package. The shim only ever connects to 127.0.0.1 (or, under WSL in NAT networking mode, the Windows host). Speech transcription is performed by the desktop app, which routes it through Prodius' EU inference gateway — see prodius.ai/privacy.

• No third-party dependencies, by design. Everything is Python standard library, so the shim installs in a second and adds no supply-chain surface to your agent's environment.

• The bridge is plain HTTP, so anything that can curl can reach you too — cron jobs, deploy scripts, CI. That endpoint is the desktop app's, not this package's; see prodius.ai/connect.

Configuration

The shim auto-discovers the running Prodius app. You rarely need to set anything, but these environment variables override the defaults:

Console scripts

• prodius-mcp — the MCP server (run by your AI tool, not by hand).

• prodius-mcp-reset — resets the Prodius conversation. Wire it to a Claude Code SessionStart hook (see the snippet above) so a new session doesn't inherit stale context.

• prodius-permission-hook — answers Claude Code's permission prompts by voice, so you can say "allow" / "deny" from anywhere. Add it as a PermissionRequest hook in ~/.claude/settings.json:

  "hooks": {
    "PermissionRequest": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "prodius-permission-hook" }] }
    ]
  }

  It only runs when Claude Code itself would ask you, after its own permission modes and allow/deny rules, and offers Allow once, Always allow and Deny. Always allow saves exactly the rule Claude Code's own prompt would offer. If Prodius isn't running or you don't answer, you get the normal terminal prompt, so it never blocks you.

  Set it up under PreToolUse before version 0.3? Move it to PermissionRequest. Under PreToolUse the hook now does nothing.

Troubleshooting

• Popup doesn't appear? Confirm the Prodius desktop app is running with Voice Bridge enabled, and that prodius-mcp is on your PATH.

• Agent doesn't receive your answer? Check your microphone works in Prodius (try a normal dictation), then restart your AI tool after editing its config.

• Two overlays for the same agent? Only the first shim process registered for an agent may show overlays; later ones get a 409 suppressed and stay quiet. If overlays stop appearing entirely, restart the desktop app to clear the registration.

Development

git clone <repo-url> && cd prodius-mcp
pip install -e . pytest
python -m pytest tests/

The tests don't need the desktop app: they run the server as a subprocess and talk JSON-RPC to it over stdio.

The package is stdlib-only and must stay that way — dependencies in pyproject.toml is deliberately empty, and tests/test_version.py guards the single-sourced version (pyproject.toml is the one version string; __init__.py reads it back via importlib.metadata).

Versioning and releases

Only MAJOR.MINOR in pyproject.toml is meaningful in git. At release time ci/inject_pypi_version.sh sets the patch number to the CI pipeline ID and adds a PEP 440 suffix per channel (X.Y.N stable, X.Y.Nb1 beta, X.Y.N.dev1 everything else), so every build has a unique version. ci/local_validate.sh rehearses the whole release (inject, version guard, tests, build, twine check, wheel smoke test) locally without uploading.

License

MIT — see LICENSE.

Note that this covers the shim only. The Prodius desktop app it connects to is closed-source and separately licensed; it is free to use on the Free tier. See prodius.ai.