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, 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

pnpm add @struktoai/mirage-agents @struktoai/mirage-browser @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

Tool	Maps to
`execute_command`	`Workspace.execute()`, the full shell pipeline (cat, grep, find, pipe, …).
`read`	Line-paginated file read with `offset` and `limit`.
`write`	Create a new file (fails if it already exists).
`edit`	Replace a string in an existing file.
`ls`	List a directory.
`grep`	Recursive `grep -rn` over the workspace.

Exports

Symbol	Purpose
`MirageServer`	In-process MCP server exposing the Mirage tools; pass to `options.mcpServers`.
`buildOptions`	Returns ready-to-use query `Options` backed by a workspace.
`buildSystemPrompt`	Generates a system prompt that describes mounted paths to the model.
`MIRAGE_SYSTEM_PROMPT`	The default system prompt template.

Getting Started

Agents

Resources

Runtimes

Claude Agent SDK

Install

Usage

Composing with other MCP servers

Tools

Exports

​Install

​Usage

​Composing with other MCP servers

​Tools

​Exports

Install

Usage

Composing with other MCP servers

Tools

Exports