# Claude Code + Reflex MCP Quickstart
Get Reflex working as an MCP tool server inside Claude Code in under 5 minutes.
---
## Prerequisites
- [Claude Code](https://claude.ai/code) installed and working
- A project directory you want to search
---
## Step 1 — Install Reflex
**Via npm (recommended):**
```bash
npm install -g reflex-search
```
**Via cargo:**
```bash
cargo install reflex-search
```
Verify the install:
```bash
rfx --version
```
> **Cargo users:** If `rfx` is not found after install, add `~/.cargo/bin` to your `PATH`:
> ```bash
> export PATH="$HOME/.cargo/bin:$PATH"
> ```
---
## Step 2 — Add Reflex to Claude Code
Open your Claude Code MCP settings file. The right scope depends on your use case:
| All projects (global) | `~/.claude/claude_code_config.json` |
| This project only | `.claude/claude_code_config.json` |
Add the `reflex` entry under `mcpServers`:
```json
{
"mcpServers": {
"reflex": {
"command": "rfx",
"args": ["mcp"],
"env": {},
"disabled": false
}
}
}
```
> **Note:** `rfx mcp` runs as a stdio MCP server. Claude Code starts and manages it
> automatically — you should not run this command manually in your terminal.
After saving, restart Claude Code (or use **Reload Window** in VS Code) to pick up the
new server.
---
## Step 3 — Index your project
Navigate to your project root and build the search index:
```bash
cd /path/to/your/project
rfx index
```
Indexing is incremental: subsequent runs only process changed files. The first index on a
typical project (10–50k files) takes a few seconds.
> **Tip:** Add `.reflex/` to your `.gitignore` to keep the cache local.
> ```
> echo ".reflex/" >> .gitignore
> ```
---
## Step 4 — Your first search
In a Claude Code conversation, ask a question that requires code search. Claude invokes
Reflex automatically via MCP:
> *"Where is the `parse_config` function defined in this project?"*
Behind the scenes, Claude calls the `search_code` tool:
```json
{
"tool": "search_code",
"arguments": {
"pattern": "parse_config",
"symbols": true
}
}
```
The response includes exact file paths, line numbers, and code previews — no shell
scripting or manual `grep` required.
---
## Key Tools for AI Agents
The five tools Claude uses most often in a Reflex-indexed codebase:
### `search_code` — find anything
Full-text or symbol-only search with line numbers and code previews.
```json
// All usages of a function
{ "pattern": "process_request" }
// Definitions only (not usages)
{ "pattern": "process_request", "symbols": true }
// Filter to a specific language
{ "pattern": "process_request", "lang": "rust", "symbols": true }
// Scope to a subdirectory
{ "pattern": "process_request", "glob": ["src/api/**/*.rs"] }
```
### `list_locations` — where, without the noise
Returns `[{path, line}]` only — no code previews. Use this to quickly enumerate all
locations before deciding which files to read.
```json
{ "pattern": "TODO" }
// → [{"path": "src/auth.rs", "line": 42}, {"path": "src/cache.rs", "line": 7}, ...]
```
### `gather_context` — orient to a new project
Returns directory structure, detected frameworks, entry points, and file-type
distribution. Run this at the start of a session when you are unfamiliar with a codebase.
```json
{ "structure": true, "framework": true, "entry_points": true }
```
### `get_dependencies` — what does this file import?
Returns all static imports for a file with their classification
(internal / external / stdlib).
```json
{ "path": "src/auth/middleware.rs" }
```
### `index_project` — keep the index fresh
Trigger a reindex after code changes (git pull, file creation, refactor).
```json
{}
// Force a full rebuild if results seem wrong:
{ "force": true }
```
> **Planned:** `find_references` for cross-file symbol usage tracking is coming in a
> future release.
---
## Tips
### Re-indexing after code changes
Reflex does not watch for changes by default. Re-index manually after significant edits:
```bash
rfx index # Fast incremental update (changed files only)
rfx index --force # Full rebuild from scratch
```
Or run the watcher to keep the index live during active development:
```bash
rfx watch
```
### Glob filters in monorepos
Scope searches to a specific package or service to reduce noise:
```json
{
"pattern": "useAuth",
"glob": ["packages/web/**/*.ts"]
}
```
### Excluding noisy directories
```json
{
"pattern": "TODO",
"exclude": ["**/node_modules/**", "**/vendor/**", "**/target/**"]
}
```
### Index staleness detection
When Claude gets results that look stale, it can call `index_project` to refresh and then
retry — all within the same conversation. You do not need to leave the chat.
---
## Troubleshooting
### "Index not found" error
The `.reflex/` cache has not been built yet for this directory. Run `rfx index` from the
**project root** — the same directory you opened in Claude Code.
```bash
rfx index
```
### Missing new files or stale results
After pulling changes or creating files, the index may lag behind. Re-index:
```bash
rfx index
```
If errors persist after an incremental index, force a full rebuild:
```bash
rfx index --force
```
### MCP server not connecting
1. Confirm `rfx` is on your `PATH`:
```bash
which rfx
```
2. Check the settings JSON for syntax errors — trailing commas and unquoted keys break
JSON parsing.
3. Restart Claude Code after editing the config file.
4. Check Claude Code's MCP server logs for error output from `rfx mcp`.
### MCP server exits unexpectedly
`rfx mcp` runs as a long-lived process over stdio. If it exits unexpectedly, Claude Code
will surface an error in the tool result. Run `rfx mcp` manually in a terminal to see any
startup errors, then report a bug with the output.
---
## Legacy: CLI / JSON Mode
If you are integrating Reflex into a shell script or non-MCP agent, you can use the
`--json` flag directly on the CLI:
```bash
rfx query "pattern" --json
```
### JSON Output Format
The `--json` response includes a `metadata` block for staleness detection:
```json
{
"metadata": {
"status": "fresh",
"current_branch": "main",
"indexed_branch": "main",
"current_commit": "74eb454...",
"indexed_commit": "74eb454..."
},
"results": [
{
"path": "./src/cache.rs",
"lang": "rust",
"kind": "Struct",
"symbol": "CacheManager",
"span": { "start_line": 42, "start_col": 0, "end_line": 45, "end_col": 1 },
"preview": "pub struct CacheManager {"
}
]
}
```
**`metadata.status` values:**
| `fresh` | Index is up to date |
| `branch_not_indexed` | Current git branch has not been indexed |
| `commit_changed` | HEAD has moved since last index |
| `files_modified` | Files modified since last index (detected via sampling) |
When `status !== "fresh"`, the response also includes `reason` (human-readable
explanation) and `action_required` (command to fix, typically `"rfx index"`).
### Bash example
```bash
#!/bin/bash
response=$(rfx query "pattern" --json)
if [ "$status" != "fresh" ]; then
echo "Index stale, re-indexing..." >&2
rfx index
response=$(rfx query "pattern" --json)
fi
### Python example
```python
import subprocess, json
def query_with_auto_reindex(pattern: str):
response = json.loads(
subprocess.check_output(["rfx", "query", pattern, "--json"])
)
if response["metadata"]["status"] != "fresh":
print(f"Index stale: {response['metadata']['reason']}")
subprocess.run(["rfx", "index"], check=True)
response = json.loads(
subprocess.check_output(["rfx", "query", pattern, "--json"])
)
return response["results"]
```
### Exit codes
| `0` | Success (results found, index fresh) |
| `1` | No results found or error |