MCP and Agent Workflows¶

repoctx can run as a stdio MCP server so agent hosts can ask for repository context without scraping terminal output.

Start The Server¶

Install the CLI first:

npm install -g @nugehs/repoctx
repoctx doctor

Or run via npx without installing — recommended for MCP host configs:

npx -y @nugehs/repoctx mcp

repoctx mcp

From a local checkout:

node src/cli.js mcp

The MCP server uses stdio. The agent host starts repoctx mcp as a child process and speaks JSON-RPC over standard input and output.

MCP Client Examples¶

Use the installed binary when possible. If a host cannot find repoctx, replace "repoctx" with the full path from command -v repoctx on macOS/Linux or where repoctx on Windows.

Generic stdio client¶

Many MCP clients use this shape:

{
  "mcpServers": {
    "repoctx": {
      "command": "repoctx",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Some hosts also require an explicit "type": "stdio" field. Check the host's current MCP schema before copying a config into a shared repository.

For a local checkout instead of a global install:

{
  "mcpServers": {
    "repoctx": {
      "command": "node",
      "args": ["/path/to/repoctx/src/cli.js", "mcp"],
      "env": {}
    }
  }
}

Keep /path/to/repoctx as a private local path. Do not commit machine-specific absolute paths to public documentation or shared repositories.

Claude Desktop¶

Claude Desktop uses claude_desktop_config.json with a top-level mcpServers object.

{
  "mcpServers": {
    "repoctx": {
      "type": "stdio",
      "command": "repoctx",
      "args": ["mcp"],
      "env": {}
    }
  }
}

After editing the config, fully restart Claude Desktop. If the server does not appear, run repoctx doctor and repoctx mcp manually in a terminal first, then check the MCP logs for the host.

Reference: Model Context Protocol local server guide.

VS Code¶

VS Code stores MCP server configuration in mcp.json. Workspace-level configuration lives at .vscode/mcp.json; user-level configuration is also supported by VS Code.

VS Code uses a top-level servers object:

{
  "servers": {
    "repoctx": {
      "type": "stdio",
      "command": "repoctx",
      "args": ["mcp"]
    }
  }
}

Useful commands from the Command Palette:

• MCP: Add Server
• MCP: List Servers
• MCP: Reset Cached Tools
• MCP: Open Workspace Folder MCP Configuration
• MCP: Open User Configuration

Reference: VS Code MCP configuration reference.

Cursor¶

Cursor uses mcp.json with a top-level mcpServers object.

{
  "mcpServers": {
    "repoctx": {
      "command": "repoctx",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Use a project config when repoctx should only be available for one workspace. Use a global config only when you want the server available across projects.

Reference: Cursor MCP docs.

MCP Tool Surface¶

repoctx 2.3 exposes 13 canonical MCP tools. Legacy names (pr_review, merge_readiness, find_*, etc.) still work via tools/call until v3.0 — see Migration to 2.0.

Agent Loop¶

Host Guidance¶