> ## 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's 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](/python/agents/claude-code), which points the `claude` CLI at a [FUSE](/python/setup/fuse) mountpoint. Use this SDK integration when you build your own agent with `claude_agent_sdk.query()` and want Mirage tools rather than the built-in file tools.

## Install

```bash theme={null}
uv add 'mirage-ai[claude-agent-sdk]'
```

## Usage

`build_options` wires a workspace into a ready-to-use `ClaudeAgentOptions`: it registers the Mirage MCP server, restricts the agent to Mirage's tools, and injects a system prompt describing the mounted paths.

```python theme={null}
from claude_agent_sdk import query

from mirage import Workspace
from mirage.agents.claude_agent_sdk import build_options
from mirage.vfs.s3 import S3Config, S3VFS

ws = Workspace({"/s3": S3VFS(S3Config(bucket="my-bucket"))})

async for msg in query(
    prompt="cat /s3/data.csv | grep error",
    options=await build_options(ws),
):
    print(msg)
```

## Composing with other MCP servers

Use `MirageServer` directly to combine Mirage with other servers:

```python theme={null}
from claude_agent_sdk import ClaudeAgentOptions

from mirage.agents.claude_agent_sdk import MirageServer, build_system_prompt

options = ClaudeAgentOptions(
    mcp_servers={"mirage": MirageServer(ws), "github": github_server},
    allowed_tools=["mcp__mirage__*", "mcp__github__*"],
    tools=[],
    system_prompt=await build_system_prompt(workspace=ws),
)
```

## Tools

The server serves the session's seven tools, [`session.tools`](/python/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 `ClaudeAgentOptions(mcp_servers=...)`. |
| `build_options` | Returns a ready-to-use `ClaudeAgentOptions` backed by a workspace. |
| `build_system_prompt` | 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.