Relace

You run an MCP server to enable AI-powered, instant code merging and semantic codebase search for Relace. This server lets you connect your editor or tooling to Relace using a simple, standardized MCP interface, so you can apply changes quickly, search your codebase with natural language, and synchronize with Relace Cloud for powerful semantic understanding.

How to use

You can connect common MCP clients to the Relace MCP Server to start applying edits, searching your codebase, and syncing with the cloud. Use the client that fits your workflow and follow its setup steps to point at your MCP server configuration.

Typical usage patterns include: applying code edits produced by the Relace AI, performing fast natural-language searches across your repository, and keeping a cloud copy in sync for enhanced semantic search. Additionally, you can explore your project with dedicated exploration tools provided by the MCP ecosystem.

How to install

Prerequisites you need before running the MCP server:

• uv — Python package manager
• git — for cloud_sync to respect .gitignore
• ripgrep (rg) — recommended for fast_search (falls back to Python regex if unavailable)

Platform notes to ensure you have the right environment for smooth operation:

• Linux — Fully supported
• macOS — Fully supported
• Windows — Partial; bash tool unavailable; use WSL for full parity or rely on other exploration tools such as view_file, grep_search, or glob

Configure the MCP client to connect to Relace using one of the supported clients. The example below demonstrates how to configure a stdio-based setup using the Relace MCP server. Copy the configuration into your MCP client settings. The exact path depends on the client you choose.

Configuration and runtime details

The Relace MCP Server relies on a small set of environment variables to operate. Set these in your MCP client configuration or in your shell environment.

Key environment variables you will use:

• RELACE_API_KEY: API key from Relace Dashboard (required)
• RELACE_BASE_DIR: Absolute path to your project root (optional; auto-detected if not set)
• RELACE_DEFAULT_ENCODING: Optional file encoding override for legacy repos
• RELACE_ENCODING_SAMPLE_LIMIT: Optional limit for auto-detecting encoding (default 30)

Troubleshooting

If you encounter common issues, check these points first to resolve most problems quickly.

• RELACE_API_KEY is not set: Set the key in your environment or MCP config.
• RELACE_BASE_DIR does not exist or is invalid: Ensure the path exists and is within RELACE_BASE_DIR.
• NEEDS_MORE_CONTEXT or APPLY_NOOP: Include 1–3 real anchor lines before and after the target block.
• FILE_TOO_LARGE: Large files may exceed limits; split or adjust processing.
• ENCODING_ERROR: Explicitly set RELACE_DEFAULT_ENCODING if auto-detection fails.
• FILE_NOT_WRITABLE or PERMISSION_ERROR: Check write permissions for files and directories.
• AUTH_ERROR: Verify your RELACE_API_KEY is valid and not expired.
• RATE_LIMIT: Wait and retry after a short delay.
• TIMEOUT_ERROR or NETWORK_ERROR: Check network connectivity; adjust timeout if needed.

Windows users should note that the bash tool is unavailable. Use Windows Subsystem for Linux (WSL) for full parity, or rely on alternative exploration tools supported by your setup.

Development notes

If you are developing or testing locally, you can explore the project by cloning the MCP client and running local experiments. Use the provided commands to set up and verify behavior.

Examples and tools you can use with the MCP server

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

Notes on available tools

The MCP server provides several tools for code editing, search, and cloud integration. These tools are designed to work together to optimize your coding workflow and project understanding.

Available tools

fast_apply

Apply code edits at 10,000+ tokens/sec via Relace API

fast_search

Agentic codebase search with natural language queries

cloud_sync

Upload local codebase to Relace Cloud for semantic search

cloud_search

Semantic search over cloud-synced repositories

cloud_list

List cloud repositories in your Relace account

cloud_info

Get sync status of cloud repositories

cloud_clear

Delete cloud repository and local state