Claude Code + Reflex MCP Quickstart

Get Reflex working as an MCP tool server inside Claude Code in under 5 minutes.

---

Prerequisites

• Claude Code installed and working
• A project directory you want to search

---

Step 1 — Install Reflex

Via npm (recommended):

npm install -g reflex-search

Via cargo:

cargo install reflex-search

Verify the install:

rfx --version

Cargo users: If rfx is not found after install, add ~/.cargo/bin to your PATH:

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:

Scope	File
All projects (global)	~/.claude/claude_code_config.json
This project only	.claude/claude_code_config.json

Add the reflex entry under mcpServers:

{
  "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:

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:

{
  "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.

// 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.

{ "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.

{ "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).

{ "path": "src/auth/middleware.rs" }

index_project — keep the index fresh

Trigger a reindex after code changes (git pull, file creation, refactor).

{}

// 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:

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:

rfx watch

Glob filters in monorepos

Scope searches to a specific package or service to reduce noise:

{
  "pattern": "useAuth",
  "glob": ["packages/web/**/*.ts"]
}

Excluding noisy directories

{
  "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.

rfx index

Missing new files or stale results

After pulling changes or creating files, the index may lag behind. Re-index:

rfx index

If errors persist after an incremental index, force a full rebuild:

rfx index --force

MCP server not connecting

1. Confirm rfx is on your PATH:

   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:

rfx query "pattern" --json

JSON Output Format

The --json response includes a metadata block for staleness detection:

{
  "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:

Value	Meaning
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

#!/bin/bash
response=$(rfx query "pattern" --json)
status=$(echo "$response" | jq -r '.metadata.status')

if [ "$status" != "fresh" ]; then
    echo "Index stale, re-indexing..." >&2
    rfx index
    response=$(rfx query "pattern" --json)
fi

echo "$response" | jq '.results'

Python example

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

Code	Meaning
0	Success (results found, index fresh)
1	No results found or error