MCP

Every workspace on the Mirage server is an MCP 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.

Claude Code
Cursor
VS Code
Codex

claude mcp add mirage -- mirage mcp -w demo

.cursor/mcp.json

{
  "mcpServers": {
    "mirage": { "command": "mirage", "args": ["mcp", "-w", "demo"] }
  }
}

.vscode/mcp.json

{
  "servers": {
    "mirage": { "type": "stdio", "command": "mirage", "args": ["mcp", "-w", "demo"] }
  }
}

~/.codex/config.toml

[mcp_servers.mirage]
command = "mirage"
args = ["mcp", "-w", "demo"]

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

Claude Code
Cursor
VS Code
Codex

claude mcp add --transport http mirage https://mirage.example.com/v1/workspaces/demo/mcp \
  --header "Authorization: Bearer $MIRAGE_TOKEN"

.cursor/mcp.json

{
  "mcpServers": {
    "mirage": {
      "url": "https://mirage.example.com/v1/workspaces/demo/mcp",
      "headers": { "Authorization": "Bearer ${env:MIRAGE_TOKEN}" }
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "mirage": {
      "type": "http",
      "url": "https://mirage.example.com/v1/workspaces/demo/mcp",
      "headers": { "Authorization": "Bearer ${env:MIRAGE_TOKEN}" }
    }
  }
}

~/.codex/config.toml

[mcp_servers.mirage]
url = "https://mirage.example.com/v1/workspaces/demo/mcp"
bearer_token_env_var = "MIRAGE_TOKEN"

Auth

The endpoint takes the same bearer token as the HTTP API. 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. read, ls, grep and glob are marked read-only. A session is offered the ones its profile 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 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.

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

Getting Started

Access

Policy

Learn

Help

VFS

CLIs

Runtimes

Connect

Auth

Tools

VFS calls and explain

Sessions

​Connect

​Auth

​Tools

​VFS calls and explain

​Sessions

Connect

Auth

Tools

VFS calls and explain

Sessions