> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Agent SDK

> Run @anthropic-ai/claude-agent-sdk against a Mirage workspace through an in-process MCP server of Mirage's tools.

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 theme={null}
  pnpm add @struktoai/mirage-agents @struktoai/mirage-node @anthropic-ai/claude-agent-sdk
  ```

  ```bash Browser theme={null}
  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 theme={null}
import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
import { query } from '@anthropic-ai/claude-agent-sdk'
import { buildOptions } from '@struktoai/mirage-agents/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:

```ts theme={null}
import { MirageServer, buildSystemPrompt } from '@struktoai/mirage-agents/claude-agent-sdk'

const options = {
  mcpServers: { mirage: MirageServer(ws), github: githubServer },
  allowedTools: ['mcp__mirage__*', 'mcp__github__*'],
  systemPrompt: await buildSystemPrompt({ workspace: ws }),
}
```

## Tools

The server serves the session's seven tools, [`session.tools`](/typescript/access/in-app#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` | 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.