oxy mcp: Oxygen for AI agents
oxy mcp serves one repository to an AI agent over the
Model Context Protocol (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:
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.
commitandamendtake the paths to include, orall: true; never neither. - Nothing destructive by default.
undois not offered, andpushrefusesforce, unless the server is started with--allow-destructive. Tag withdrawal, bookmark deletion and history rewriting are not tools at all. Each tool carries MCP'sreadOnlyHintanddestructiveHint. - Values are never flags. Arguments are passed as
--flag=valueand 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):
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.