relace

This MCP server wraps Relace’s AI-powered code editing and exploration capabilities for your codebase. It exposes the core tools you’d expect from Relace integrations, including fast apply for edits at high throughput, agentic search for natural-language driven codebase exploration, agentic retrieval for two-stage semantic + agentic retrieval, and cloud search as an optional semantic search across cloud-synced repos. To operate, you’ll run the MCP through uv with the relace-mcp entrypoint, authenticated via your Relace API key. With the proper environment variables, you can query, navigate, and apply changes to your project directly from your MCP-enabled client or editor integration. The server is designed to work with the various MCP clients documented in the README (Cursor, Windsurf, VS Code, Codex CLI), each of which passes requests to the Relace backend through the configured uv tool runner.

To use, set RELACE_API_KEY in your MCP config or environment, and optionally enable cloud tools with RELACE_CLOUD_TOOLS=1 or enable agentic_retrieval by setting MCP_SEARCH_RETRIEVAL=1. Core tools such as fast_apply and agentic_search are always available. You can invoke agentic retrieval if you want the two-stage retrieval flow, or rely on the cloud tools for cloud-backed search across your repositories. Ensure MCP_BASE_DIR points to your project root if you want the MCP to auto-detect paths. Once configured, initiate the relace-mcp server via your preferred MCP client (Cursor, Windsurf, VS Code, Codex CLI) and begin querying or applying changes against your codebase.

Prerequisites:

• Python 3.11+ (recommended)
• uv tool (Relace MCP runner) installed or available in your environment
• git, ripgrep (recommended)

Step-by-step installation:

1. Install prerequisites (example commands):

   • Python 3.11+ installed from python.org or via your system package manager
   • Install uv (per Relace docs). If your setup uses uv tooling, install it following the official guidance (the README examples assume uv is available as a command).
   • Ensure git and ripgrep are installed:
     • macOS: brew install git ripgrep
     • Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y git ripgrep
     • Windows: install via the Git for Windows installer and ripgrep via scoop/choco if desired

2. Prepare MCP config (example):

   • Create an MCP config file in your preferred client location. For example, in Cursor, Windsurf, or VS Code, you’ll reference the relace-mcp setup as shown in the README. A minimal configuration to run Relace MCP locally:

   { "mcpServers": { "relace": { "command": "uv", "args": ["tool", "run", "relace-mcp"], "env": { "RELACE_API_KEY": "rlc-your-api-key", "MCP_BASE_DIR": "/absolute/path/to/your/project" } } } }

3. Run the MCP server:

   • Ensure your RELACE_API_KEY is set in the environment or in the MCP config as shown above.
   • Start the server via your MCP client configuration. For example, using the Cursor/MCP.json example, the server is started by the configured uv tool running the relace-mcp entrypoint.

4. Verify operation:

   • Connect with your MCP client (Cursor, Windsurf, VS Code, Codex CLI) using the relace server name and verify that you can run a quick search or apply a small code edit through the agentic tools or fast_apply.

Notes:

• The MCP_BASE_DIR is optional but recommended if you want the MCP to operate relative to your project root.
• If you plan to use cloud tools or agentic_retrieval, set MCP_SEARCH_RETRIEVAL=1 and/or RELACE_CLOUD_TOOLS=1 in your environment or config.
• Refer to the README for exact client integration steps for Cursor, Windsurf, VS Code, and Codex CLI.

Tips and common considerations:

• Ensure RELACE_API_KEY is kept secret; do not commit it to public repos or share in logs.
• If you encounter RELACE_API_KEY is not set, check that your MCP config or environment is loaded by the MCP client and that the key is accessible to the uv runner.
• To enable agentic_retrieval, set MCP_SEARCH_RETRIEVAL=1; to enable cloud-based tools, set RELACE_CLOUD_TOOLS=1.
• If you see FILE_TOO_LARGE or ENCODING_ERROR errors, adjust your file handling or encoding settings per the troubleshooting notes in the README.
• The Platform Support and Troubleshooting sections in the README provide guidance for cross-platform usage and common failures.