Ekamyth Agent OS docs
Standard OS / Services and devices

How MCP works with Ekamyth Agent OS

By default, your agent's MCP tool calls reach Agent OS through its hooks, like its other tools: on Claude Code, and on Codex when the call reaches the hook. For a server you want checked call by call before it's reached, you set up the MCP wrapper for that server. Agent OS also has a small MCP server of its own.

How does MCP work with Agent OS?

MCP is how an agent such as Claude Code or Codex reaches tools and data outside itself. Agent OS takes part in that in two ways, and you choose each one by adding it to your agent's MCP configuration yourself. hero mcp never edits that configuration.

Without the wrapper, Agent OS still sees your agent's MCP calls through its hook, as it does the agent's other tools: on Claude Code, and on Codex when the call reaches the hook. By default, a send, post or delete through an MCP tool is held for your approval, and a search goes through. See What the hook sees.

Your agent uses hero mcp for Agent OS resources and tools, and reaches your own MCP server through the MCP wrapper, which checks each call first. You approve or deny held calls at your terminal. A dashed line shows that your agent can still call the server through its original entry, outside the wrapper.
Both pieces run on your machine. The wrapper checks only calls that go through it.

Agent OS doesn't provide an MCP SDK

Agent OS isn't a way to build MCP servers or agents. It installs the MCP SDK only for its own use, in an environment only Agent OS uses. It provides the wrapper, which you can put in front of a local MCP server you already use, and its own small server. Both run on your machine over standard input and output, started by your agent.

MCP concepts

TermWhat it means
MCP serverA program that offers tools or data to your agent over MCP. Your agent starts the ones listed in its MCP configuration.
hero mcpAgent OS's own MCP server: a short list of Agent OS resources and two tools.
MCP wrapperhero mcp wrap <server>, which re-serves one of your MCP servers so that each call is checked before it runs.
Held callA wrapped call waiting for your decision. It expires after 60 seconds.
Invocation idThe id of one wrapped call, mcpinv- followed by 32 hex characters. You approve or deny a held call by its id.
CoverageWhether an entry in your agent's config goes through the wrapper (governed) or not (inventory-only).
ReceiptAgent OS's record of how a wrapped call ended, kept on your machine, with no argument content.

How the MCP wrapper decides what runs

The wrapper asks your Agent OS policy about each call before it reaches your server. See How governance works.

AnswerWhat happensWhat your agent sees
AllowThe call goes to your server once.—
Needs approvalThe call is held for 60 seconds while you approve or deny it at your terminal.A tool error with hero_state approval_required and the invocation id.
DenyThe call doesn't run.A tool error with hero_state denied.

Limits: the result of a call you approve doesn't reach your agent. Your agent can still call your server through its original entry, and those calls don't go through the wrapper. Agent OS doesn't stop that.

What leaves your machine

Held calls stay on your machine. A call's arguments are never stored as text, only as a keyed fingerprint. When your agent reads your Brain or approval status through hero mcp, that text goes to your agent over standard input and output, and Agent OS can't tell which of it your agent then includes in its requests to your model provider, so treat it as possible model context. The wrapper also records metadata about each action. Don't assume every MCP record stays on your machine: if you set up trace export, those records go where you send them.

When something goes wrong

What happensWhat you seeWhat happens to the work
The wrapper can't use your server: not found, defined in both agents' configs, remote rather than local, carrying secrets in its definition, or itself a wrapperThe wrapper refuses to start, with a hero mcp: MCP server '<name>' … lineYour agent can't reach that server through the wrapper.
Your server can't start, or the wrapper can't open its connection for approvalsThe wrapper exits with a hero mcp: lineYour agent gets no answer from the wrapper.
You don't decide a held call in 60 secondsIt expiresThe call doesn't run.
The wrapper restartsCalls it was holding are abandonedThey don't run.
You deny a call after the wrapper has stoppeddeniedThe denial is recorded, without a receipt.
HERO_MCP=off is sethero mcp: HERO_MCP is offNeither hero mcp nor the wrapper starts.
Your agent uses another MCP protocol versionIts first request gets unsupportedhero mcp serves nothing to that agent.
Your agent's config still has the server's original entryhero mcp status reports that entry as inventory-onlyYour agent can still call the server through that entry, and those calls don't go through the wrapper. Agent OS doesn't stop that.

MCP on Claude Code and Codex

Claude CodeCodex
Where the wrapper looks for your servers~/.claude.json, mcpServers~/.codex/config.toml, mcp_servers

What you can change in MCP

SettingDefaultEffect
Your agent's MCP configurationNeither piece addedWhether your agent uses hero mcp, and which servers go through the wrapper. See The MCP wrapper.
Your Agent OS policyA tool not marked as reviewed is heldWhich wrapped calls run, are held or are refused. See hero govern.
HERO_MCP=offOnStops hero mcp and the wrapper from starting. To stop a wrapper that's running, stop the agent that started it.
HERO_CLAUDE_CONFIG, HERO_CODEX_CONFIG~/.claude.json, ~/.codex/config.tomlWhere hero mcp reads your agents' MCP configuration.

See MCP for yourself

For a server named in your agent's MCP configuration, run:

# Whether that entry goes through the wrapper, and whether the wrapper is running
hero mcp status <server>

For the output, see Example output.

MCP limits and next steps

See Limits of hero mcp.

Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.