> For the complete documentation index, see [llms.txt](https://metalbear.com/mirrord/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://metalbear.com/mirrord/docs/use-cases/using-mirrord-with-ai/mcp-server.md). # mirrord MCP Server Register the MCP server built into the mirrord CLI, so that your AI agent checks mirrord configs and reads the mirrord docs of the version you have installed. The mirrord CLI includes an [MCP](https://modelcontextprotocol.io) server, `mirrord mcp`. It gives an AI agent tools to validate `mirrord.json` and `mirrord-up.yaml` against the schema of your installed mirrord version, to explain config options, and to search and read the mirrord docs and [skills](https://metalbear.com/mirrord/docs/use-cases/using-mirrord-with-ai/ai-skills-plugin.md) that this version ships with. It works offline and never starts a session. ## What you need * mirrord CLI `3.273.0` or later. Check with `mirrord --version`, and see [Install mirrord](https://metalbear.com/mirrord/docs/getting-started/quick-start/install-mirrord.md). * An agent that supports MCP servers over stdio, such as Claude Code, Codex, Cursor, VS Code, Windsurf, Claude Desktop, or OpenCode. ## Register the server Use the absolute path to the `mirrord` binary. Clients that start from a desktop launcher don't inherit your shell's `PATH`. To find the path, run: ```sh which mirrord ``` On Windows, run `where mirrord`. Replace `/absolute/path/to/mirrord` below with the output. {% tabs %} {% tab title="Claude Code" %} ```sh claude mcp add --scope user mirrord -- /absolute/path/to/mirrord mcp ``` {% endtab %} {% tab title="Codex" %} ```sh codex mcp add mirrord -- /absolute/path/to/mirrord mcp ``` {% endtab %} {% tab title="Cursor, Windsurf, Claude Desktop" %} Add the entry under `"mcpServers"` in the client's config file: * Cursor: `~/.cursor/mcp.json`, or `.cursor/mcp.json` in the project. * Windsurf: `~/.codeium/windsurf/mcp_config.json`. * Claude Desktop: `claude_desktop_config.json`, in `~/Library/Application Support/Claude/` on macOS and `%APPDATA%\Claude\` on Windows. ```json "mirrord": { "command": "/absolute/path/to/mirrord", "args": ["mcp"] } ``` {% endtab %} {% tab title="VS Code" %} Add the entry under `"servers"` in `.vscode/mcp.json`: ```json "mirrord": { "type": "stdio", "command": "/absolute/path/to/mirrord", "args": ["mcp"] } ``` {% endtab %} {% tab title="OpenCode" %} Add the entry under `"mcp"` in `~/.config/opencode/opencode.json`: ```json "mirrord": { "type": "local", "command": ["/absolute/path/to/mirrord", "mcp"], "enabled": true } ``` {% endtab %} {% endtabs %} Restart the client after you register the server. To check the connection, ask the agent to validate your `.mirrord/mirrord.json` with the `validate_config` tool. If the client lists no `mirrord` tools, check the path in the entry with `/absolute/path/to/mirrord mcp --help`. ## Tools | Tool | What it does | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `validate_config` | Checks the content of a `mirrord.json` or `mirrord-up.yaml` against the schema of the installed version. Returns each issue with the path of the value, a message, and the allowed values. An empty `issues` list means the config is valid. | | `explain_config_option` | Explains one option by its dotted path, such as `feature.network.incoming.mode`: what it does, the values it takes, its default, and the mirrord plan it needs. | | `get_skill` | Lists the mirrord skills, or returns one skill and the files it bundles. | | `search_docs` | Searches the docs, skills, and config options by keywords, and returns the best matching pages. | | `read_doc` | Returns the full Markdown of one page or config option that `search_docs` found. Without a path, lists every page. | ## Resources and prompts * `mirrord://info`: the installed mirrord version. The docs and skills the server answers from are those of that version. * `mirrord://docs/`: each docs page. * `mirrord://skills/`: each skill. Each skill is also an MCP prompt. ## What the server tells the agent The server sends the agent instructions when it connects. They tell the agent to: * Get the matching skill with `get_skill` before it starts a mirrord task. * Validate every config with `validate_config` before it writes the file, and fix issues until none remain. * Answer questions about mirrord with `search_docs` and `read_doc`, not from memory. * Default to `mirror` for incoming traffic, and on a shared cluster use `steal` only with an HTTP filter. * Target staging or development clusters, never production. ## Versions The docs, skills, and config schema come from the installed mirrord binary, so the answers match the version you run. To get newer docs and skills, upgrade mirrord. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://metalbear.com/mirrord/docs/use-cases/using-mirrord-with-ai/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.