Skip to main content
Every workspace on the Mirage server is an MCP server at:
An agent connected to it gets a shell and six file tools over the workspace’s files.

Connect

On your own machine, let the client launch mirage mcp. It starts the server if needed and sends your token. These examples use the demo workspace from the CLI quickstart.
For a server elsewhere, give the client the URL and a token:

Auth

MCP uses the same bearer token as HTTP. mirage mcp sends the CLI’s token for you: a saved login, MIRAGE_TOKEN, or the local token file. A client that connects by URL sends the header itself; the endpoint does not start an OAuth sign-in.

Tools

Every tool answers text, with isError set when it fails. A session sees only the tools its session profile allows: shell needs a command its commands lets run, ls and grep need those commands, and write and edit need a mount the session may write. A tool it does not see answers not found.

shell

Runs a shell line in the session’s working directory. A cd or export holds for the next call.
string
required
The line to run.
Answers stdout, then stderr. isError is set when the line exits non-zero.

read

Reads a file as numbered lines.
string
required
Absolute path of the file.
integer
default:"0"
First line to return, zero-based.
integer
default:"2000"
Most lines to return.

write

Writes a file, creating missing parent directories. To replace a file that exists, read all of it first; the write fails if it changed since. Use edit to change part of a file.
string
required
Absolute path of the file.
string
required
The text to write.

edit

Replaces a string in a file. Fails if the file changed since it was read, or if old_string is missing or appears more than once without replace_all.
string
required
Absolute path of the file.
string
required
The exact text to replace.
string
required
The text to put in its place.
boolean
default:"false"
Replace every occurrence.

ls

Lists a directory, one name per line.
string
required
Absolute path of the directory.

grep

Searches files under a path for a regular expression, as grep -rn does. Finding nothing is not an error.
string
required
The regular expression.
string
required
Absolute path of the file or directory to search.
boolean
default:"false"
Match case-insensitively (-i).
boolean
default:"false"
Read the pattern as plain text (-F).
string
Search only files whose name matches this glob, such as *.py (--include).
integer
Lines of context around each match (-C).
boolean
default:"false"
Print only the names of matching files (-l).
boolean
default:"false"
Print only a count of matching lines per file (-c).
integer
Stop each file after this many matches (-m).

glob

Finds files whose path matches a pattern, sorted. ** matches any number of directories. A pattern that matches more files than a mount’s walk_limit is an error that names the limit.
string
required
The pattern, such as **/*.py. A relative one is matched under path.
string
default:"/"
The directory a relative pattern is matched under.

Output progress

A shell call can send output previews while it runs. Pass a progress token in the request’s _meta:
Mirage then sends notifications/progress messages that start with [stdout] or [stderr], over HTTP and mirage mcp alike. Previews are trimmed and batched, so take the full output from the final result.

VFS calls

Add ?calls=all to the URL, or --all-calls to mirage mcp, for 23 more tools: vfs_read, vfs_is_dir and the rest, one per VFS call. They take the same arguments and return the same JSON as HTTP. A failed call sets isError and answers the HTTP error object as its text, such as {"code": "not_found", "message": "No such file or directory", "errno": "ENOENT"}. With them enabled, shell and every vfs_<call> also take explain: true, which reports what the call would do without running it; 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 session 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.