# oxy mcp: Oxygen for AI agents

`oxy mcp` serves one repository to an AI agent over the

[Model Context Protocol](https://modelcontextprotocol.io) (MCP), on stdio

(oxygen#159). The agent calls typed tools (`status`, `log`, `commit`, …)

and gets JSON back, instead of running `oxy` in a shell and reading its

output.

## Who changes are signed as

The server signs as whatever identity its environment configures, exactly

as `oxy` would: it runs each tool as this same `oxy` binary, in the

repository, with the server's environment. Start it from an agent home and

every change the agent makes is sealed **via the agent**, with no

`OXY_HOME` to remember on each command:

```sh

OXY_HOME=~/.oxy-agents/claude oxy mcp ~/development/myproject

```

The server says who it signs as in its `initialize` reply (the first line

of `oxy identity show`), and the `identity` tool shows the rest. Without an

identity, reading works and committing is refused with oxy's own message.

## Tools

Each tool returns the command's `--json` output as structured content (an

array comes wrapped as `{"result": […]}`) and as text. A failed command is a

tool result with `isError: true` and oxy's error, so the agent sees why.

| Tool | Runs | Arguments |

|---|---|---|

| `status` | `oxy status --json` | |

| `diff` | `oxy diff [CHANGE] --json` | `change` |

| `log` | `oxy log --json` | `revset`, `path`, `limit` (default 20, at most 1000) |

| `show` | `oxy show CHANGE --json` | `change` (default `@`), `stat` |

| `cat` | `oxy cat PATH [-r CHANGE]` | `path`, `change` |

| `blame` | `oxy blame PATH --json` | `path` |

| `bookmarks` | `oxy bookmark list --json` | `all` |

| `tags` | `oxy tag list --json` | |

| `conflicts` | `oxy resolve --json` (report only) | |

| `op_log` | `oxy op log --json` | `limit` |

| `identity` | `oxy identity show` | |

| `commit` | `oxy commit -m MESSAGE PATHS…` | `message`, and `paths` or `all: true` |

| `amend` | `oxy amend [-m] PATHS…` | `paths` or `all: true`, `message` |

| `describe` | `oxy describe [CHANGE] -m MESSAGE` | `message`, `change` |

| `fetch`, `pull` | `oxy fetch\|pull [REMOTE] --json` | `remote` |

| `push` | `oxy push [REMOTE] --json` | `remote`, `bookmark`, `force` |

| `tlog_verify` | `oxy tlog verify --json` | |

| `undo` | `oxy undo` | only with `--allow-destructive` |

## Safety

- **Commits are deliberate.** `commit` and `amend` take the paths to

  include, or `all: true`; never neither.

- **Nothing destructive by default.** `undo` is not offered, and `push`

  refuses `force`, unless the server is started with `--allow-destructive`.

  Tag withdrawal, bookmark deletion and history rewriting are not tools at

  all. Each tool carries MCP's `readOnlyHint` and `destructiveHint`.

- **Values are never flags.** Arguments are passed as `--flag=value` and

  after `--`, so a path or message starting with `-` stays a value.

- **Your policy still applies.** Pushes go through the remote's checks and

  the repository's trust policy like any other; an agent's delegation

  scope limits what its seals may do.

- **Output is bounded.** A tool's text stops at 256 KiB, saying to narrow

  the request.

## Adding it to an agent

Claude Code, for one project (run in the project's root):

```sh

claude mcp add oxy -- env OXY_HOME=$HOME/.oxy-agents/claude oxy mcp

```

Any MCP client that starts stdio servers takes the same command: `oxy mcp

[DIR] [--allow-destructive]`, with `OXY_HOME` set for an agent's identity.

`DIR` defaults to the current directory and must be a repository's root.