Workspace as an in-process MCP server, so every file and shell call the agent makes runs in the workspace, not on the host. To run the claude CLI itself on a workspace, see Claude Code.
Install
Usage
build_options returns a ClaudeAgentOptions that registers the Mirage server, turns off Claude’s built-in tools, allows Mirage’s and sets a system prompt describing the mounts:
build_options(ws, session_id="agent") runs the tools as that session, under its profile. Create the session first with ws.session. system_prompt= replaces the default prompt.
Tools
The server serves the session’s seven tools,session.tools: shell, read, write, edit, ls, grep and glob, named mcp__mirage__<tool> in the SDK. It carries only the ones the session’s profile leaves it, so a read-only workspace gets no write or edit.
Other MCP servers
MirageServer is the server alone. Put it next to other servers in a ClaudeAgentOptions of its own:
tools=[] keeps Claude’s built-in tools out, and allowed_tools lets the listed servers run without a permission prompt.
Keep Claude’s Bash
To keep Claude’s own Bash tool and run it in a workspace, point the SDK atmirage-bash, as for Claude Code. Mirage’s other tools come over mirage mcp in place of Claude’s file tools. Both reach one workspace that the Mirage daemon serves:
- Bash runs in the workspace. Mirage’s
read,write,edit,ls,grepandglobreplace Claude’s Read, Edit, Write, Glob and Grep, so every file the agent touches goes through Mirage. - Mount the project and
/tmpat their own paths, as the Claude Code page shows, socdcarries over. - To run under a profile, create a session with
mirage workspace session create -w demo -s agent -p reviewer, setMIRAGE_SESSIONtoagentand add-s agentto themirage mcparguments.
Exports
Examples
all_tools.pyhas a Sonnet agent call each of the seven tools on a RAM workspace and checks the file it leaves.