Connect
On your own machine, let the client launchmirage mcp. It starts the server if needed and sends your token.
These examples use the demo workspace from the CLI quickstart.
- Claude Code
- Cursor
- VS Code
- Codex
- Claude Code
- Cursor
- VS Code
- Codex
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, withisError 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. Acd or export holds
for the next call.
Answers stdout, then stderr. isError is set when the line exits non-zero.
read
Reads a file as numbered lines.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.
edit
Replaces a string in a file. Fails if the file changed since it was read, or ifold_string is missing or appears more than once without replace_all.
ls
Lists a directory, one name per line.grep
Searches files under a path for a regular expression, asgrep -rn does.
Finding nothing is not an error.
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.
Output progress
Ashell call can send output previews while it runs. Pass a progress token in
the request’s _meta:
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.