Skip to content

MCP

Quick Setup

# Codex: use agent installer (includes MCP wiring)
cgrep agent install codex

# Direct MCP host install examples
cgrep mcp install claude-code
cgrep mcp install cursor
cgrep mcp install vscode

Canonical MCP fast path

  1. cgrep map for a quick repo overview
  2. agent locate / cgrep_agent_locate to find candidate regions
  3. agent expand / cgrep_agent_expand to expand only selected hits
  4. cgrep read for full-file or section reads
  5. definition / references / callers for impact follow-up

Use cgrep agent plan "..." as an optional CLI-only stage 0 before this flow when the task is broad or ambiguous. It is a preflight helper, not an MCP tool call.

If a call is noisy, empty, slow, or capped, rescope first with path → glob → changed → file_type, then lower limit / context. For smaller payloads, prefer profile=agent.

Supported mcp install hosts: - claude-code - cursor - windsurf - vscode - claude-desktop

Run MCP Server Manually (Debug)

cgrep mcp serve

Common MCP Tools

  • cgrep_search
  • cgrep_read
  • cgrep_map
  • cgrep_definition
  • cgrep_references
  • cgrep_callers
  • cgrep_symbols
  • cgrep_dependents
  • cgrep_agent_locate
  • cgrep_agent_expand
  • Human CLI fast path:
  • search
  • read
  • definition / references / callers
  • Agent / MCP fast path:
  • map
  • agent locate
  • agent expand
  • read
  • definition / references / callers
  • agent plan is optional CLI-only stage 0 when the task is broad or ambiguous.
  • If locate/expand is already clear, skip agent plan.

Search Requests: mode vs profile

Keep these concepts separate in MCP clients:

  • mode = search engine choice
  • keyword
  • semantic
  • hybrid
  • profile = retrieval defaults / output ergonomics
  • human
  • agent
  • fast

Compatibility behavior for MCP search:

  • mode=auto → use the current default search behavior
  • mode=default → same as above

These are compatibility aliases, not separate engine modes.

Example MCP calls:

{"query":"token validation","mode":"auto"}
{"query":"token validation","profile":"agent"}
{"query":"token validation","mode":"keyword","profile":"agent"}

Narrow Scope First

When search feels noisy or expensive, narrow the request before widening it:

  • path → start with the smallest relevant subtree (src/auth, src/query, etc.)
  • glob → keep one file family in scope (*.rs, src/**/*.ts)
  • changed → focus on recent edits first (true/HEAD/revision string)
  • file_type → constrain language/file-type when the query is broad
  • profile=agent → smaller, more agent-friendly payload defaults
  • mode → engine choice only; do not use it for retrieval presets

Example narrowing pattern:

{
  "query": "retry budget",
  "path": "src",
  "glob": "*.rs",
  "changed": "HEAD",
  "file_type": "rust",
  "profile": "agent"
}

Behavior You Should Know

  • Most MCP tools default to auto_index=true.
  • If index is missing, first call bootstraps it automatically.
  • Refresh is call-driven + file-change-aware while MCP server is alive.
  • No always-on periodic reindex loop is required for normal MCP usage.
  • Semantic/hybrid mode is experimental and still needs embeddings index.

Timeout / Output-Cap / Restart-Rescope Guidance

If an MCP tool call times out or says output exceeded the cap:

  1. Rescope first with path, then glob, then changed, then file_type.
  2. Reduce result volume (limit, context) before widening scope again.
  3. For search-heavy agent flows, prefer profile=agent (and CLI --budget tight when relevant).
  4. If you made large edits and the client/server state still looks stale, restart the MCP session and retry the narrowed request.

Troubleshooting

  • If an MCP client sends mode=auto, cgrep treats that as “use the default search path.”
  • If you want explicit engine control, use mode=keyword|semantic|hybrid.
  • If you want smaller, agent-friendly payloads, use profile=agent.
  • If a tool call times out, rescope with path / glob / changed / file_type before retrying.
  • If output is too large, lower limit / context or switch to profile=agent.
# Verify MCP server handshake quickly
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| cgrep mcp serve

If path resolution looks wrong, pass cwd in MCP tool arguments. If a long-lived debug session still looks stale after major edits, restart cgrep mcp serve and retry the narrowed request.