Skip to main content
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, which points the claude CLI at a FUSE mountpoint. 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. 
from claude_agent_sdk import query

from mirage import Workspace
from mirage.agents.claude_agent_sdk import build_options
from mirage.resource.s3 import S3Config, S3Resource

ws = Workspace({"/s3": S3Resource(S3Config(bucket="my-bucket"))})

async for msg in query(
    prompt="cat /s3/data.csv | grep error",
    options=build_options(ws),
):
    print(msg)

​
Composing with other MCP servers

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=build_system_prompt(workspace=ws),
)

​
Tools

ToolMaps to
execute_commandWorkspace.execute(), the full shell pipeline (cat, grep, find, pipe, …).
readLine-paginated file read with offset and limit.
writeCreate a new file (fails if it already exists).
editReplace a string in an existing file.
lsList a directory.
grepRecursive grep -rn over the workspace.

​
Exports

SymbolPurpose
MirageServerIn-process MCP server exposing the Mirage tools; pass to ClaudeAgentOptions(mcp_servers=...).
build_optionsReturns a ready-to-use ClaudeAgentOptions backed by a workspace.
build_system_promptGenerates a system prompt that describes mounted paths to the model.
MIRAGE_SYSTEM_PROMPTThe default system prompt template.