prodius-mcp
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@prodius-mcp Ask me out loud whether to deploy to production before you push."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpIf 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-mcpFor 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:prodiusCursor / 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
Tool | What it does |
| Pops a question on your screen and captures your spoken (or typed) reply. Supports optional clickable answer buttons (max 4), an expandable Markdown |
| Shows you a short message in a desktop overlay, fire-and-forget. Takes |
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
curlcan 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:
Variable | Purpose | Default |
| Auth token for the local Prodius server. | Read from the Prodius app's |
| Prodius local server URL. | Discovered from settings ( |
| Label shown so you know which agent is asking. |
|
| Set to | off |
| Set to | off |
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 CodeSessionStarthook (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 aPermissionRequesthook 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
PreToolUsebefore version 0.3? Move it toPermissionRequest. UnderPreToolUsethe hook now does nothing.
Troubleshooting
Popup doesn't appear? Confirm the Prodius desktop app is running with Voice Bridge enabled, and that
prodius-mcpis on yourPATH.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 suppressedand 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.
Available Tools
2 toolsask_userARead-only
Ask the user a question via voice overlay. Sub-agents must NOT call this — return results to your parent agent. Plain text, one sentence, ~80 chars (100 max).
Inputs: question (required), detail, options, task_name, +1 more.
notifyARead-only
Show the user a short message in a desktop overlay, without waiting for a reply. Use it as often as the user's own instructions say; with no such instructions, only for results they need to see while away from the terminal. Sub-agents must NOT call this.
Inputs: message (required), level, detail, task_name.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct semantics: ask_user blocks for a reply, while notify sends a non-blocking message. An agent can easily choose between them based on whether user input is required.
Both names are lowercase and readable, but ask_user follows a verb_noun pattern while notify is a bare verb. The minor inconsistency does not create confusion.
Two tools is thin, but the server's apparent scope is limited to user overlay communication. Each tool earns its place, though the surface feels minimal.
The core interaction modes—asking for input and sending notifications—are covered. Minor gaps might include confirmation-specific helpers, but agents can work around them.
Maintenance
Related MCP Connectors
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
An MCP connector that lets your AI agents ask you questions, request permission approvals, and send alerts as push notifications to your phone and mac notch, so you can unblock and approve your agents from anywhere.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Related MCP Servers
- AlicenseAqualityDmaintenanceManage voice AI agents from Claude Code, Cursor, VS Code, or any MCP-compatible assistant.310 npm3MIT
- AlicenseBqualityDmaintenanceA zero-friction stdio MCP bridge connecting Cursor Desktop to a local Hermes Agent, enabling natural language task delegation with session continuity and profile awareness.42Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides sound alerts, voice messages, and macOS notifications for Claude Code and other MCP-compatible AI assistants.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to access local voice synthesis, zero-shot cloning, and voice catalog tools through native MCP tool calls for applications like Claude and Cursor.37 npmAGPL 3.0