pyro-mcp/docs/integrations.md

Chat Host Integrations

This page documents the intended product path for pyro-mcp:

• validate the host with the CLI
• run pyro mcp serve
• connect a chat host
• let the agent work inside disposable workspaces

pyro-mcp currently has no users. Expect breaking changes while this chat-host path is still being shaped.

Use this page after you have already validated the host and guest execution through install.md or first-run.md.

Recommended Modes

Use a named mode when one workflow already matches the job:

pyro host connect codex --mode repro-fix
pyro host connect codex --mode inspect
pyro host connect claude-code --mode cold-start
pyro host connect claude-code --mode review-eval

The mode-backed raw server forms are:

pyro mcp serve --mode repro-fix
pyro mcp serve --mode inspect
pyro mcp serve --mode cold-start
pyro mcp serve --mode review-eval

Use the generic no-mode path only when the named mode feels too narrow.

Generic Default

Bare pyro mcp serve starts workspace-core. From a repo root, it also auto-detects the current Git checkout so the first workspace_create can omit seed_path. That is the product path.

pyro mcp serve

If the host does not preserve cwd, fall back to:

pyro mcp serve --project-path /abs/path/to/repo

If you are outside a repo checkout entirely, start from a clean clone source:

pyro mcp serve --repo-url https://github.com/example/project.git

Use --profile workspace-full only when the chat truly needs shells, services, snapshots, secrets, network policy, or disk tools.

Helper First

Use the helper flow before the raw host CLI commands:

pyro host connect codex --mode repro-fix
pyro host connect codex --mode inspect
pyro host connect claude-code --mode cold-start
pyro host connect claude-code --mode review-eval
pyro host print-config opencode --mode repro-fix
pyro host doctor
pyro host repair opencode

These helpers wrap the same pyro mcp serve entrypoint, make named modes the first user-facing story, and still leave the generic no-mode path available when a mode is too narrow.

Claude Code

Preferred:

pyro host connect claude-code --mode cold-start

Repair:

pyro host repair claude-code

Package without install:

claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start
claude mcp list

If Claude Code launches the server from an unexpected cwd, use:

claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start --project-path /abs/path/to/repo

Already installed:

claude mcp add pyro -- pyro mcp serve
claude mcp list

Reference:

• claude_code_mcp.md

Codex

Preferred:

pyro host connect codex --mode repro-fix

Repair:

pyro host repair codex

Package without install:

codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix
codex mcp list

If Codex launches the server from an unexpected cwd, use:

codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix --project-path /abs/path/to/repo

Already installed:

codex mcp add pyro -- pyro mcp serve
codex mcp list

Reference:

• codex_mcp.md

OpenCode

Preferred:

pyro host print-config opencode
pyro host repair opencode

Use the local MCP config shape from:

• opencode_mcp_config.json

Minimal opencode.json snippet:

{
  "mcp": {
    "pyro": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "--from", "pyro-mcp", "pyro", "mcp", "serve", "--mode", "repro-fix"]
    }
  }
}

If pyro-mcp is already installed, replace uvx --from pyro-mcp pyro with pyro in the same config shape.

If OpenCode launches the server from an unexpected cwd, add "--project-path", "/abs/path/to/repo" after "serve" in the same command array.

Generic MCP Fallback

Use this only when the host expects a plain mcpServers JSON config, when the named modes are too narrow, and when it does not already have a dedicated example in the repo:

• mcp_client_config.md

Generic mcpServers shape:

{
  "mcpServers": {
    "pyro": {
      "command": "uvx",
      "args": ["--from", "pyro-mcp", "pyro", "mcp", "serve"]
    }
  }
}

When To Use workspace-full

Stay on bare pyro mcp serve unless the chat host truly needs:

• persistent PTY shell sessions
• long-running services and readiness probes
• secrets
• guest networking and published ports
• stopped-workspace disk inspection or raw ext4 export

When that is necessary:

pyro mcp serve --profile workspace-full

Recipe-Backed Workflows

Once the host is connected, move to the five real workflows in use-cases/README.md:

• cold-start repo validation
• repro plus fix loops
• parallel isolated workspaces
• unsafe or untrusted code inspection
• review and evaluation workflows

Validate the whole story with:

make smoke-use-cases