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