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

# MCP

> Connect Claude Code, Cursor, VS Code or Codex to a workspace.

Every workspace on the Mirage server is an [MCP](https://modelcontextprotocol.io) server at:

```
http://127.0.0.1:8765/v1/workspaces/{id}/mcp
```

## Connect

On your own machine, let the client launch `mirage mcp`. It starts the server if needed and sends your token.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add mirage -- mirage mcp -w demo
    ```
  </Tab>

  <Tab title="Cursor">
    ```json .cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "mirage": { "command": "mirage", "args": ["mcp", "-w", "demo"] }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    ```json .vscode/mcp.json theme={null}
    {
      "servers": {
        "mirage": { "type": "stdio", "command": "mirage", "args": ["mcp", "-w", "demo"] }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    ```toml ~/.codex/config.toml theme={null}
    [mcp_servers.mirage]
    command = "mirage"
    args = ["mcp", "-w", "demo"]
    ```
  </Tab>
</Tabs>

For a server elsewhere, give the client the URL and a token:

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http mirage https://mirage.example.com/v1/workspaces/demo/mcp \
      --header "Authorization: Bearer $MIRAGE_TOKEN"
    ```
  </Tab>

  <Tab title="Cursor">
    ```json .cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "mirage": {
          "url": "https://mirage.example.com/v1/workspaces/demo/mcp",
          "headers": { "Authorization": "Bearer ${env:MIRAGE_TOKEN}" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    ```json .vscode/mcp.json theme={null}
    {
      "servers": {
        "mirage": {
          "type": "http",
          "url": "https://mirage.example.com/v1/workspaces/demo/mcp",
          "headers": { "Authorization": "Bearer ${env:MIRAGE_TOKEN}" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    ```toml ~/.codex/config.toml theme={null}
    [mcp_servers.mirage]
    url = "https://mirage.example.com/v1/workspaces/demo/mcp"
    bearer_token_env_var = "MIRAGE_TOKEN"
    ```
  </Tab>
</Tabs>

## Auth

The endpoint takes the same bearer token as the [HTTP API](/home/access/http#auth). `mirage mcp` reads it from `MIRAGE_TOKEN` or `~/.mirage/auth_token`. The server does not offer OAuth sign-in, so a client must send the header.

## Tools

| Tool | Does |
| - | - |
| `shell` | Run a bash line. |
| `read` | Read a file, or a range of its lines. |
| `write` | Write a file. |
| `edit` | Replace a string in a file. |
| `ls` | List a directory. |
| `grep` | Search file contents. |
| `glob` | Find paths by pattern. |

Their inputs are listed under [Call a tool](/home/access/http#call-a-tool). `read`, `ls`, `grep` and `glob` are marked read-only. A session is offered the ones its [profile](/home/policy/policies#which-door-enforces-what) leaves it: `shell` needs a command the allow list installs, `ls` and `grep` those commands, `write` and `edit` a mount the session may write. A tool it is not offered is `not found`.

## VFS calls and explain

Add `?calls=all` to the URL, or `--all-calls` to `mirage mcp`, to also list each of the 24 [VFS calls](/home/access/http#call-the-vfs) as a tool named `vfs_<call>` (`vfs_read`, `vfs_is_dir`), with the same arguments. Each answers the route's JSON as text; a failed one answers `{detail, errno, refusal}` with `isError` set. `shell` and every `vfs_<call>` then take `explain: true`, which answers what the call would do and runs nothing; see [Explain](/home/policy/explain).

## Sessions

Calls run in the workspace's default session. To use another, add `?session_id=<id>` to the URL, or `-s <id>` to `mirage mcp`. The session's [profile](/home/permissions) applies as it does to a shell line: a path hidden from `cat` is hidden from `read`. Command rules apply only to `shell`, `ls` and `grep`.


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