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.

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

Learn

Help

VFS

CLIs

Runtimes

Connect

Auth

Tools

Sessions

​Connect

​Auth

​Tools

​Sessions

Connect

Auth

Tools

Sessions