---
title: Claude Agent SDK
description: Run @anthropic-ai/claude-agent-sdk against a Mirage workspace via an in-process MCP server exposing execute, read, write, edit, ls, and grep tools.
icon: /images/claude-logo.svg
---

The [Claude Agent SDK](https://code.claude.com/docs/en/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](/typescript/agents/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.

<CodeGroup>
```bash Node
pnpm add @struktoai/mirage-agents @struktoai/mirage-node @anthropic-ai/claude-agent-sdk
```
```bash Browser
pnpm add @struktoai/mirage-agents @struktoai/mirage-browser @anthropic-ai/claude-agent-sdk
```
</CodeGroup>

## 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.

```ts
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:

```ts
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. |
