iowap-client-mcp

MCP toolkit for IOWAP: run a curated IOWAP toolset from any MCP-speaking agent — without teaching every agent the node CLI's pitfalls.

The problem

IOWAP is a distributed capability mesh: the relay routes tasks, nodes execute them. Today, an AI agent that wants to use IOWAP shells out to node-cli --json. That works, but every agent has to relearn the same pitfalls itself: response envelopes that must be unwrapped, node IDs vs. names, the global flag position, which commands are safe and which mutate the node. Knowledge ends up in one agent's skill file instead of in code.

Related MCP server: Codex Harness MCP

The answer

iowap-mcp is an MCP stdio server that wraps node-cli behind a small, curated toolset:

The node CLI remains the source of truth for authentication and execution — the server adds zero credential handling of its own. Destructive commands (register, update, daemon control, capability publishing) are deliberately not exposed.

Trust model: whoever can launch iowap-mcp on the host acts with the host's node identity — an MCP client spawning this server is a trusted executor. Environment filtering of the stdio subprocess is host behavior; the package relies on the node's on-disk identity and enforces none of it itself.

Narrowable execution: operators can restrict which capabilities task_submit may fire with IOWAP_ALLOW_CAPS=cap.one,cap.two (csv env, unset means all) — with hermes mcp add that is an --env line away. artifact_download writes a file: an existing path is refused unless overwrite: true states the replacement explicitly.

Scope is one host: the server binds the local node to local MCP clients. There is deliberately no remote/HTTP variant — the node identity stays on the machine that owns it. POSIX host (Linux/macOS) — no Windows support.

Install

pip install "iowap-client-mcp[mcp]"

…or let the local node install it: node-cli mcp install (own venv, client-neutral, PyPI registry). Requires a node installation of IOWAP on the same host (see iowap-node) — the server shells out to the installed node-cli. Both wheels are regular PyPI packages: node-cli update check/apply keeps node and toolkit current together (toolkit upgrades need no service restart — the server process reloads on the next client spawn).

Wire it into an MCP client

Example for Hermes Agent (~/.hermes/config.yaml):

mcp_servers:
  iowap:
    command: "iowap-mcp"

Or: hermes mcp add iowap --command iowap-mcp

Any other MCP client uses the equivalent stdio spawn (command = iowap-mcp). Tested with Hermes Agent (hermes mcp add + /reload-mcp, live against a running relay) and Codex (OpenAI) — same stdio command, zero per-client code.

Development

python -m venv .venv && .venv/bin/pip install -e ".[mcp,dev]"
.venv/bin/pytest

License

MIT — see LICENSE.