MCP Integration

Zenus supports the Model Context Protocol in both directions: it can expose its tools to any MCP client, and it can consume tools from external MCP servers.

Install the optional dependency first:

pip install 'zenus-core[mcp]'
# or
pip install mcp

MCP server mode

Zenus exposes every tool action as an individual MCP tool. Tool names follow the {ToolName}__{action_name} convention:

FileOps__read_file
FileOps__write_file
GitOps__git_commit
SystemOps__get_cpu_usage
...

Start the server

zenus mcp-server                         # stdio (default — for Claude Code, Cline)
zenus mcp-server --transport sse         # HTTP SSE
zenus mcp-server --transport sse --port 8765 --host 0.0.0.0
zenus mcp-server --allow-privileged      # also expose ShellOps and CodeExec

Configure via config.yaml

mcp:
  server:
    enabled: true
    transport: stdio
    allow_privileged: false

Connect from Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "zenus": {
      "command": "zenus",
      "args": ["mcp-server"]
    }
  }
}

Privilege tiers

By default, ShellOps and CodeExec are excluded from MCP exposure — they can execute arbitrary code and are restricted to trusted, local environments.

Enable them explicitly:

mcp:
  server:
    allow_privileged: true

Or set MCP_ALLOW_PRIVILEGED=1 in your environment.

MCP client mode

Zenus can connect to external MCP servers at startup and inject their tools into its own registry — making them available to the orchestrator alongside native Zenus tools.

Injected tools follow the naming pattern: mcp__{server_name}__{tool_name}.

Configure in config.yaml

mcp:
  client:
    enabled: true
    servers:
      # stdio transport — subprocess spawn
      - name: filesystem
        transport: stdio
        command: "uvx mcp-server-filesystem /home/user/projects"
        env:
          SOME_VAR: value

      # SSE transport — HTTP endpoint
      - name: remote-tools
        transport: sse
        url: "http://localhost:9000/sse"

How it works

1. At startup, MCPClientRegistry connects to each configured server.
2. Tools are discovered via session.list_tools().
3. Each tool is wrapped as an MCPRemoteTool and injected into TOOLS.
4. The orchestrator dispatches to them transparently — no special handling needed.

Connection failures are logged as warnings and do not crash Zenus. If a server is unavailable, its tools are simply absent from the registry.

Supported transports