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 the SDK’s query() and want Mirage tools rather than the built-in file tools.

​
Install

@struktoai/mirage-agents/claude-agent-sdk is runtime-agnostic. Pair it with @struktoai/mirage-node for Node or @struktoai/mirage-browser for the browser. 
pnpm add @struktoai/mirage-agents @struktoai/mirage-node @anthropic-ai/claude-agent-sdk

​
Usage

buildOptions wires a workspace into ready-to-use query options: it registers the Mirage MCP server, restricts the agent to Mirage’s tools, and injects a system prompt describing the mounted paths. 
import { MountMode, OpsRegistry, RAMResource, Workspace } from '@struktoai/mirage-node'
import { query } from '@anthropic-ai/claude-agent-sdk'
import { buildOptions } from '@struktoai/mirage-agents/claude-agent-sdk'

const ram = new RAMResource()
const ops = new OpsRegistry()
for (const op of ram.ops()) ops.register(op)
const ws = new Workspace({ '/': ram }, { mode: MountMode.WRITE, ops })

for await (const msg of query({
  prompt: "Write /hello.txt with 'hi from mirage', then cat it.",
  options: buildOptions(ws),
})) {
  console.log(msg)
}

​
Composing with other MCP servers

Use MirageServer directly to combine Mirage with other servers: 
import { MirageServer, buildSystemPrompt } from '@struktoai/mirage-agents/claude-agent-sdk'

const options = {
  mcpServers: { mirage: MirageServer(ws), github: githubServer },
  allowedTools: ['mcp__mirage__*', 'mcp__github__*'],
  systemPrompt: buildSystemPrompt({ 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 options.mcpServers.
buildOptionsReturns ready-to-use query Options backed by a workspace.
buildSystemPromptGenerates a system prompt that describes mounted paths to the model.
MIRAGE_SYSTEM_PROMPTThe default system prompt template.