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

Install

Use this integration from Node. The Claude Agent SDK launches the native Claude Code runtime, so the complete query() workflow does not run in a browser.

pnpm add @struktoai/mirage-claude-agent-sdk @struktoai/mirage-node @anthropic-ai/claude-agent-sdk

Usage

buildOptions adds and preapproves Mirage tools, turns off the SDK’s built-in tools, and describes the mounted paths in the system prompt.

import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
import { query } from '@anthropic-ai/claude-agent-sdk'
import { buildOptions } from '@struktoai/mirage-claude-agent-sdk'

const ws = new Workspace({ '/': new RAMVFS() }, { mode: MountMode.WRITE })

for await (const msg of query({
  prompt: "Write /hello.txt with 'hi from mirage', then cat it.",
  options: await 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-claude-agent-sdk'

const options = {
  mcpServers: { mirage: MirageServer(ws), github: githubServer },
  allowedTools: ['mcp__mirage__*', 'mcp__github__*'],
  tools: [],
  systemPrompt: await buildSystemPrompt({ 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 type { Options } from '@anthropic-ai/claude-agent-sdk'

const options: Options = {
  cwd: '/Users/me/project',
  env: {
    ...process.env,
    CLAUDE_CODE_SHELL: '/Users/me/.local/bin/mirage-bash',
    MIRAGE_WORKSPACE: 'demo',
  },
  mcpServers: {
    mirage: { type: 'stdio', command: 'mirage', args: ['mcp', '-w', 'demo'] },
  },
  allowedTools: ['Bash', 'mcp__mirage__*'],
  disallowedTools: ['Read', 'Edit', 'Write', 'Glob', 'Grep', 'mcp__mirage__shell'],
}

env replaces the environment Claude Code starts with, so keep process.env in it. command -v mirage-bash prints the path.

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`	An in-process MCP server exposing the Mirage tools; pass it to `options.mcpServers`.
`buildOptions`	Returns ready-to-use query `Options` backed by a workspace: the `MirageServer` tools as the `mirage` MCP server, preapproved, and a system prompt describing the mounts. The SDK’s built-in tools are disabled, so the Mirage tools are the agent’s only file access layer.
`BuildOptionsOptions`	Options for `buildOptions`: `systemPrompt` replaces the generated prompt, and `sessionId` names the Mirage session the tools act as.
`MIRAGE_SYSTEM_PROMPT`	The default system prompt: how the Mirage filesystem differs from a plain one.
`buildSystemPrompt`	Returns `MIRAGE_SYSTEM_PROMPT` followed by a description of the mounted paths and any extra instructions, ready to use as an agent’s system prompt.
`EDIT_DESCRIPTION` `GLOB_DESCRIPTION` `GREP_DESCRIPTION` `LS_DESCRIPTION` `READ_DESCRIPTION` `SHELL_DESCRIPTION` `WRITE_DESCRIPTION`	The text a Mirage tool gives the model, shared by the MCP server and every adapter that serves Mirage’s tool table.

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