Connect an MCP Client to Gather Step

MCP (Model Context Protocol) is the standard that AI coding assistants use to pull structured context from external tools. Gather Step ships as a stdio MCP server that you run locally alongside your indexed workspace. Any MCP-aware client, such as Claude Code, Cursor, or another MCP-aware tool, can be pointed at it with a small JSON configuration entry. No network service is involved: the server reads from the same .gather-step/ state your CLI uses.

Prerequisites

Before connecting a client:

1. An indexed workspace: run gather-step --workspace /path/to/workspace index if you have not already. The MCP server reads from the indexed state; it does not build the index for you.
2. The built binary on your PATH. See Installation for build instructions.

Fast Path

For Claude Code, Gather Step writes the project-scoped .mcp.json entry:

gather-step --workspace /path/to/workspace setup-mcp --scope local

Use --scope global to write the user-scoped entry to ~/.claude.json instead. For Codex, pass --client codex to merge the server block into ~/.codex/config.toml (scope is ignored — Codex has a single global config):

gather-step --workspace /path/to/workspace setup-mcp --client codex

The command is idempotent and updates only the gather-step entry without touching other servers, keys, or comments. Restart the client afterward.

Start the Server (Smoke Test)

Verify the server starts cleanly before wiring up a client:

gather-step --workspace /path/to/workspace serve

If the index exists and the workspace config is valid, the server starts and waits for MCP requests on stdin/stdout. You will not see output until a client connects, which is expected behavior for a stdio server.

Useful flags for the serve command:

Flag	Purpose
--max-limit <N>	Cap the number of results returned per tool call (default 1000)
--server-name <NAME>	Override the MCP server name reported to clients (useful for distinguishing multiple workspaces)
--graph <PATH>	Override the default graph.redb path if you store it outside .gather-step/
--registry <PATH>	Override the default registry.json path

For most setups, no flags are needed.

Configure Claude Code

Claude Code reads MCP server configuration from two locations. Use whichever fits your workflow:

Project-scoped: .mcp.json in the project root (checked in with the repo):

{
  "mcpServers": {
    "gather-step": {
      "command": "gather-step",
      "args": [
        "--workspace",
        "/path/to/workspace",
        "serve"
      ]
    }
  }
}

User-scoped: ~/.claude.json (applies to all projects for this user):

{
  "mcpServers": {
    "gather-step": {
      "command": "gather-step",
      "args": [
        "--workspace",
        "/path/to/workspace",
        "serve"
      ]
    }
  }
}

Replace /path/to/workspace with the directory that contains your gather-step.config.yaml. The examples assume gather-step is already on your PATH.

After saving the config, restart Claude Code. The gather-step server entry should appear in the MCP server list and show a connected state.

Configure Codex CLI

Codex reads MCP servers from ~/.codex/config.toml. Add a gather-step server block that uses the same PATH command and workspace-pinned serve args:

[mcp_servers.gather-step]
command = "gather-step"
args = ["--workspace", "/path/to/workspace", "serve"]

Restart Codex after editing the config. MCP servers are loaded when the session starts, so a running Codex session will not gain mcp__gather_step tools until the next session.

On macOS, GUI-launched apps may inherit a different PATH from your shell. If an MCP client reports that it cannot spawn gather-step, compare the client’s environment with launchctl getenv PATH and make sure the install directory for gather-step is included.

Configure Cursor

Cursor supports MCP through ~/.cursor/mcp.json or through the Settings UI under MCP Servers. The JSON format is the same:

{
  "mcpServers": {
    "gather-step": {
      "command": "gather-step",
      "args": [
        "--workspace",
        "/path/to/workspace",
        "serve"
      ]
    }
  }
}

If you prefer the Settings UI, add a new server entry with the transport set to stdio, the command set to gather-step, and the arguments list containing --workspace, your workspace path, and serve.

Configure Any MCP-Aware Client

The configuration pattern above is the generic stdio MCP stanza. Any client that supports the stdio transport accepts this shape:

{
  "mcpServers": {
    "gather-step": {
      "command": "gather-step",
      "args": [
        "--workspace",
        "/path/to/workspace",
        "serve"
      ]
    }
  }
}

The contract: the client launches the binary as a child process and communicates with it over stdin/stdout using the MCP protocol. No TCP port is opened. No network traffic leaves the machine. The server process ends when the client process ends.

How Claude Code Uses It

After configuration, Claude Code does not wait for you to type Gather Step commands manually. It decides which MCP tools to call based on your question and uses those results to build its reply.

Example:

What features or pages are affected if I change CreateOrderInput?

A typical automatic sequence looks like this:

Prompt
  -> search
  -> get_symbol
  -> trace_impact
  -> get_shared_type_usage
  -> change_impact_pack
  -> Answer

This is the reason to expose the MCP tool reference at all: the assistant does the tool selection automatically, but the retrieval path is still visible and debuggable when you want to understand how an answer was assembled.

What to Call First: A Good First Five-Tool Loop

When a client connects for the first time, call these tools in order to orient before issuing deeper queries:

1. get_graph_schema_summary Returns a compact description of the node and edge kinds in the indexed graph. Use this to understand what the current workspace contains before writing queries — especially useful when the graph is unfamiliar.

2. list_repos Returns the list of repos registered in the workspace, with per-repo file and symbol counts. Use this to confirm the index is fresh and that all expected repos are present. If a repo shows zero files, it likely was not indexed successfully.

3. search Searches the Tantivy search index for matching symbols by name or pattern. Use this to find the identifier of a symbol before using it in trace_route, context_pack, or impact calls. Searching is cheaper than a full trace and helps narrow down the target when the name is ambiguous.

4. context_pack Builds a task-shaped context slice for a given target symbol and mode. Modes include planning, debug, fix, review, and change_impact. This is the primary tool for giving an AI assistant a bounded, relevant view of the code it needs to work with — ranked items, semantic bridges, next-step suggestions, and identified gaps.

5. trace_route / trace_event trace_route answers which frontend callers reach a given backend route, which handler serves it, and what persistence hints exist downstream. trace_event follows an async event from producers to consumers across repos. Use these when the task involves debugging a specific request path or async flow in the polyrepo code graph.

pr_review (on demand) Invoked automatically when the user asks to review a pull request — for example, “review this PR using gather-step” or “what does this branch change?” It builds a disposable review index for base..head and returns a structured DeltaReport covering added/removed routes, exported symbols, payload contracts, event wiring, deployment surfaces, and removal risks. This tool works with any MCP-aware client that supports stdio transport. First runs take 30-90 seconds; cache hits complete in 1-2 seconds. Pass keep_cache: true when you need follow-up impact/trace/pack queries against the PR-branch index.

For a complete list of available MCP tools and their parameters, see the MCP tools reference.

Current Limits

• stdio transport only. There is no HTTP or SSE transport. The server must run on the same machine as the indexed workspace.
• Local-first. Generated graph state does not leave the machine. The server has no network connectivity requirements.
• Bounded results per call. Tool responses are capped to avoid overwhelming context windows. Use --max-limit if you need a smaller cap.
• Pack quality depends on index freshness. Run gather-step index or keep gather-step watch running to ensure results reflect current code. Stale indexes produce stale tool responses.

Next Steps

• Operator workflows — CLI commands for all the same capabilities the MCP tools expose.
• PR review guide — step-by-step walkthrough of the pr-review command and pr_review MCP tool.
• MCP tools reference — full tool list with parameter documentation.
• Concepts: context packs — how packs are built and what each mode emphasizes.