MCP Integration

Run grepai as an MCP server so Claude Code, Cursor, Windsurf or OpenCode can call semantic search, call tracing and index status as native tools.

grepai mcp-serve starts a local MCP server. Your AI agent can then call grepai search, trace and index tools directly instead of running shell commands.

Quick start

1. Index your project (see Prerequisites):

   grepai init
   grepai watch

2. Register the server with your agent. For Claude Code:

   claude mcp add grepai -- grepai mcp-serve

3. Restart the agent and ask a question such as “Where is user authentication handled?”. The agent calls grepai_search.

For other agents, see Configuration.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI agents call external tools. grepai works with any MCP client. This page shows the setup for Claude Code, Cursor, Windsurf and OpenCode.

Benefits

• Native tools: the agent sees typed tools with documented parameters, not a shell command to guess.
• Structured output: tools return JSON by default, or TOON (a more compact format) with format: "toon".
• Local only: the server talks to the agent over stdio. It opens no network port.

Available Tools

The server registers 14 tools.

Parameter reference

• format: json (default) or toon. Any other value returns an error.
• compact: omit code content (search) or call-site context (trace, refs) to save tokens.
• path (search only): keep results whose path starts with this prefix. Without a workspace, or with exactly one project in projects, it is relative to the project root (src/). Otherwise it must start with the project name (api/src), like grepai search --workspace --path.
• workspace: run against a workspace instead of the local project. Use grepai_list_workspaces to find names.
• projects (search) and project (trace, refs): limit a workspace query to some projects. projects is a comma-separated list. Both require workspace.
• root: absolute path of a project directory. The tool loads that project’s config and index instead of the one the server started in, so one server can serve several projects without a restart. You cannot pass both root and workspace.
• kinds (grepai_rpg_search): comma-separated list of area, category, subcategory, file, symbol, chunk.
• direction (grepai_rpg_explore): forward, reverse or both.
• edge_types (grepai_rpg_explore): comma-separated list of feature_parent, contains, invokes, imports, maps_to_chunk, semantic_sim.
• verbose (grepai_index_status): accepted, but it does not change the output today.

grepai_stats always uses the project the server started in. The RPG tools use that project too, unless you pass workspace (or the server runs with --workspace): they then read the graph of one workspace project, set with project (optional when the workspace has a single project). RPG must be enabled in that project (see RPG).

Configuration

All clients run the same command: grepai mcp-serve [project-path] [--workspace <name>]. See the mcp-serve reference.

Claude Code

Register the server with claude mcp add:

# Use the project found from the current directory
claude mcp add grepai -- grepai mcp-serve

# Use an explicit project path
claude mcp add grepai -- grepai mcp-serve /path/to/project

# Search all projects of a workspace by default
claude mcp add grepai -- grepai mcp-serve --workspace my-fullstack

Pick a scope with -s:

# User scope: available in all your Claude Code sessions
claude mcp add grepai -s user -- grepai mcp-serve --workspace my-fullstack

# Project scope: written to .mcp.json in the project
claude mcp add grepai -s project -- grepai mcp-serve

Project .mcp.json

To share the setup with your team, commit a .mcp.json file at the project root:

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve"]
    }
  }
}

For workspace mode, add the flag to args:

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve", "--workspace", "my-fullstack"]
    }
  }
}

Cursor

Add this to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve"]
    }
  }
}

On Windows, pass the project path explicitly:

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve", "C:\\path\\to\\your\\project"]
    }
  }
}

Windsurf

Add the same block to your Windsurf MCP configuration file:

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve"]
    }
  }
}

Opencode

Add a mcp entry to opencode.json at the project root, or to your global OpenCode config in ~/.config/opencode/:

{
  "mcp": {
    "grepai": {
      "type": "local",
      "enabled": true,
      "command": ["grepai", "mcp-serve"]
    }
  }
}

Workspace Mode

Start the server with --workspace to search across all projects of a workspace by default:

grepai mcp-serve --workspace my-fullstack

The server then fills in workspace for every tool that accepts it. The agent can call grepai_search with only a query. The workspace must exist in ~/.grepai/workspace.yaml. If the current directory also holds a grepai project, the server keeps it for grepai_stats.

How the server picks its target:

1. --workspace <name>, if set.
2. The project-path argument, if given. It must contain .grepai/config.yaml.
3. The nearest .grepai/config.yaml, walking up from the current directory.
4. A workspace that contains the current directory.
5. If none match but ~/.grepai/workspace.yaml defines at least one workspace, the server starts with no default target. The agent then passes workspace in each request.

If nothing matches, mcp-serve exits with an error asking you to run grepai init or use --workspace.

Usage

Once the server is configured, the agent calls the tools itself. Example calls:

Search:

Tool: grepai_search
Arguments: {"query": "user authentication flow", "limit": 5}

Search in some workspace projects, under a path:

Tool: grepai_search
Arguments: {"query": "request validation", "workspace": "my-fullstack", "projects": "backend", "path": "api/"}

Trace callers:

Tool: grepai_trace_callers
Arguments: {"symbol": "HandleLogin"}

RPG search:

Tool: grepai_rpg_search
Arguments: {"query": "command line search flow", "kinds": "symbol,file", "limit": 5}

Index status:

Tool: grepai_index_status
Arguments: {}

Prerequisites

1. grepai is installed and on your PATH.
2. The project is initialized (grepai init), or a workspace exists (grepai workspace create).
3. The index is built: grepai watch (or grepai watch --workspace my-fullstack). Trace and refs tools also need the symbol index that grepai watch builds.

Troubleshooting

Tool not appearing

• Check that grepai is on your PATH: which grepai.
• Check the syntax of your MCP configuration file.
• Restart the agent after changing the configuration.

Search returns no results

• Check the index: grepai status.
• Run grepai watch to build or update it.
• Trace and refs tools return symbol index is empty until grepai watch has run.

Connection errors

• The server uses stdio, so there is no port or network setting to check.
• Run grepai mcp-serve in a terminal from the project directory. It should start and wait for input without printing an error. Press Ctrl+C to stop it.