# 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](install.md) or [first-run.md](first-run.md).

## Recommended 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.

```bash
pyro mcp serve
```

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

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

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

```bash
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.

## Claude Code

Package without install:

```bash
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
claude mcp list
```

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

```bash
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
```

Already installed:

```bash
claude mcp add pyro -- pyro mcp serve
claude mcp list
```

Reference:

- [claude_code_mcp.md](../examples/claude_code_mcp.md)

## Codex

Package without install:

```bash
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
codex mcp list
```

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

```bash
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
```

Already installed:

```bash
codex mcp add pyro -- pyro mcp serve
codex mcp list
```

Reference:

- [codex_mcp.md](../examples/codex_mcp.md)

## OpenCode

Use the local MCP config shape from:

- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)

Minimal `opencode.json` snippet:

```json
{
  "mcp": {
    "pyro": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "--from", "pyro-mcp", "pyro", "mcp", "serve"]
    }
  }
}
```

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 and does
not already have a dedicated example in the repo:

- [mcp_client_config.md](../examples/mcp_client_config.md)

Generic `mcpServers` shape:

```json
{
  "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:

```bash
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](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:

```bash
make smoke-use-cases
```