> ## 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 via an in-process MCP server exposing execute, read, write, edit, ls, and grep 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.resource.s3 import S3Config, S3Resource

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

async for msg in query(
    prompt="cat /s3/data.csv | grep error",
    options=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=build_system_prompt(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 `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.                                                             |