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.
- The MCP wrapper,
hero mcp wrap <server>. It sits in front of one of your own local MCP servers. Your agent talks to the wrapper, which starts your server and offers its tools. Before each call runs, Agent OS checks it against your policy: the call runs, it's refused, or it's held for you to approve or deny at your terminal. Each finished call leaves a record on your machine with no argument content. You set the wrapper up one server at a time; see The MCP wrapper. hero mcp, Agent OS's own MCP server. Your agent starts it like any local MCP server. It offers your held MCP calls, the status of your local Agent OS record, and your Brain's sections to read, and two tools: deny one held call, and check the record. It can't approve anything.
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.
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
| Term | What it means |
|---|---|
| MCP server | A program that offers tools or data to your agent over MCP. Your agent starts the ones listed in its MCP configuration. |
hero mcp | Agent OS's own MCP server: a short list of Agent OS resources and two tools. |
| MCP wrapper | hero mcp wrap <server>, which re-serves one of your MCP servers so that each call is checked before it runs. |
| Held call | A wrapped call waiting for your decision. It expires after 60 seconds. |
| Invocation id | The id of one wrapped call, mcpinv- followed by 32 hex characters. You approve or deny a held call by its id. |
| Coverage | Whether an entry in your agent's config goes through the wrapper (governed) or not (inventory-only). |
| Receipt | Agent 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.
| Answer | What happens | What your agent sees |
|---|---|---|
| Allow | The call goes to your server once. | — |
| Needs approval | The 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. |
| Deny | The call doesn't run. | A tool error with hero_state denied. |
- A tool your server doesn't list is refused.
- A tool that hasn't been marked as reviewed is always held, whatever your policy says. No command marks a tool as reviewed, so out of the box every wrapped call waits for your approval.
- If your server changes a held tool's definition before you approve, the held call expires instead of running.
- Approving is for you only: at your own terminal, by typing the confirmation. It's refused when an agent runs it.
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 happens | What you see | What 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 wrapper | The wrapper refuses to start, with a hero mcp: MCP server '<name>' … line | Your agent can't reach that server through the wrapper. |
| Your server can't start, or the wrapper can't open its connection for approvals | The wrapper exits with a hero mcp: line | Your agent gets no answer from the wrapper. |
| You don't decide a held call in 60 seconds | It expires | The call doesn't run. |
| The wrapper restarts | Calls it was holding are abandoned | They don't run. |
| You deny a call after the wrapper has stopped | denied | The denial is recorded, without a receipt. |
HERO_MCP=off is set | hero mcp: HERO_MCP is off | Neither hero mcp nor the wrapper starts. |
| Your agent uses another MCP protocol version | Its first request gets unsupported | hero mcp serves nothing to that agent. |
| Your agent's config still has the server's original entry | hero mcp status reports that entry as inventory-only | Your 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 Code | Codex | |
|---|---|---|
| Where the wrapper looks for your servers | ~/.claude.json, mcpServers | ~/.codex/config.toml, mcp_servers |
What you can change in MCP
| Setting | Default | Effect |
|---|---|---|
| Your agent's MCP configuration | Neither piece added | Whether your agent uses hero mcp, and which servers go through the wrapper. See The MCP wrapper. |
| Your Agent OS policy | A tool not marked as reviewed is held | Which wrapped calls run, are held or are refused. See hero govern. |
HERO_MCP=off | On | Stops 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.toml | Where 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.