Claude Agent SDK

The Claude Agent SDK builds agents on Claude. Mirage exposes any Workspace to the SDK as an in-process MCP server, so every file and shell operation the agent runs is routed through Mirage instead of the host filesystem. This is distinct from Claude Code, the claude CLI run as it is on a workspace. Use this SDK integration when you build your own agent with claude_agent_sdk.query() and want Mirage tools rather than the built-in file tools.

Install

uv add 'mirage-ai[claude-agent-sdk]'

Usage

build_options wires a workspace into a ready-to-use ClaudeAgentOptions: it registers the Mirage MCP server, restricts the agent to Mirage’s tools, and injects a system prompt describing the mounted paths.

import asyncio

from claude_agent_sdk import query

from mirage import MountMode, RAMVFS, Workspace
from mirage.agents.claude_agent_sdk import build_options


async def main() -> None:
    ws = Workspace({"/": RAMVFS()}, mode=MountMode.WRITE)
    try:
        async for msg in query(
            prompt="Write 'hi from mirage' to /hello.txt, then cat it.",
            options=await build_options(ws),
        ):
            print(msg)
    finally:
        await ws.close()


asyncio.run(main())

Composing with other MCP servers

Inside main, use MirageServer directly to combine Mirage with other servers:

from claude_agent_sdk import ClaudeAgentOptions

from mirage.agents.claude_agent_sdk import MirageServer, build_system_prompt

options = ClaudeAgentOptions(
    mcp_servers={"mirage": MirageServer(ws), "github": github_server},
    allowed_tools=["mcp__mirage__*", "mcp__github__*"],
    tools=[],
    system_prompt=await build_system_prompt(workspace=ws),
)

Shell

To keep Claude’s own Bash tool and run it in a workspace, point the SDK at mirage-bash, as for Claude Code, and give it Mirage’s other tools over mirage mcp in place of Claude’s file tools. Both reach one workspace that the Mirage daemon serves:

mirage workspace create workspace.yaml --id demo

import shutil

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    cwd="/Users/me/project",
    env={
        "CLAUDE_CODE_SHELL": shutil.which("mirage-bash"),
        "MIRAGE_WORKSPACE": "demo",
    },
    mcp_servers={
        "mirage": {"type": "stdio", "command": "mirage", "args": ["mcp", "-w", "demo"]},
    },
    allowed_tools=["Bash", "mcp__mirage__*"],
    disallowed_tools=["Read", "Edit", "Write", "Glob", "Grep", "mcp__mirage__shell"],
)

Bash runs in the workspace, and Mirage’s read, write, edit, ls, grep and glob take the place of Claude’s Read, Edit, Write, Glob and Grep, so every file the agent touches goes through Mirage.
Mount the project and /tmp at their own paths, as the Claude Code page shows, so cd carries over.
To run under a profile, create a session with mirage session create demo --id agent -p reviewer, then set MIRAGE_SESSION to agent and add -s agent to the mirage mcp arguments.

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 the ones the session’s profile leaves it (session.tools.names()).

Exports

Symbol	Purpose
`MirageServer`	Create an in-process Mirage server for the Claude Agent SDK, with the tools the session’s profile leaves it.
`build_options`	Build ClaudeAgentOptions backed by a Mirage Workspace.
`MIRAGE_SYSTEM_PROMPT`	The default system prompt: how the Mirage filesystem differs from a plain one.
`build_system_prompt`	Build a system prompt with optional mount info and extra instructions.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Claude Agent SDK

Install

Usage

Composing with other MCP servers

Shell

Tools

Exports

​Install

​Usage

​Composing with other MCP servers

​Shell

​Tools

​Exports

Install

Usage

Composing with other MCP servers

Shell

Tools

Exports