Gctrl

Ground Control (GCTRL) MCP Server

Exposes Ground Control's knowledge management as MCP tools for Claude and other AI agents.

Tools Available

Deprecated names (alias, removal in v2)

Every tool above is also exposed under its legacy name for backwards compatibility with existing .mcp.json configs. The aliases log a deprecation warning to stderr on every invocation and will be removed in v2.0 — please migrate.

Quickstart (npm)

Published on npm as gctrl-mcp and in the official MCP Registry as io.github.GCTRL-TECH/gctrl. Add to your MCP client config (Claude Code, Claude Desktop, Cursor, Codex, …):

{  "mcpServers": {    "gctrl": {      "command": "npx",      "args": ["-y", "gctrl-mcp"],      "env": {        "GCTRL_GATEWAY_URL": "http://localhost:4000/api/agent/mcp",        "GCTRL_API_TOKEN": "gctrl_..."      }    }  }}

Requires a running GCTRL harness (get started).

Coding with GCTRL (recommended for coding agents)

Run the server in direct mode next to your gateway entry so the agent gets the local code tools, and let it keep the repository's Codebase KB current on its own:

{  "mcpServers": {    "gctrl":      { "command": "npx", "args": ["-y", "gctrl-mcp"],                    "env": { "GCTRL_GATEWAY_URL": "https://<host>/api/agent/mcp", "GCTRL_API_TOKEN": "gctrl_..." } },    "gctrl-code": { "command": "npx", "args": ["-y", "gctrl-mcp"],                    "env": { "GCTRL_API_URL": "https://<host>/api", "GCTRL_API_TOKEN": "gctrl_...",                             "GCTRL_MCP_TOOLS": "code", "GCTRL_CODE_AUTO_INDEX": "cwd" } }  }}

With GCTRL_CODE_AUTO_INDEX=cwd the server indexes the directory the MCP client launched it in (incremental - a warm repo takes seconds) right after start-up, and the agent's first gctrl_code_symbol hits a current graph. The server's instructions carry the coding protocol every connected agent follows: index once per session, navigate through gctrl_code_symbol / gctrl_code_trace / gctrl_code_architecture BEFORE reading files, run gctrl_code_impact before changing a symbol, re-index after larger edits, ask gctrl_query for the why and store decisions next to the symbols with gctrl_store. Measured on GCTRL's own repository: structural questions answered through the graph used 95.6 % fewer tokens than grep-and-read.

Configuration

| GCTRL_CODE_AUTO_INDEX | Direct mode: cwd (or a repository path) indexes that repository in the background right after start-up - incremental, never fatal. Makes the Codebase KB automatic instead of a habit. | | GCTRL_CODE_COMPILATION_ID | Direct mode: the CODE compilation gctrl_code_index uses when the agent passes none (one project = one repo = one code graph). An explicit compilationId from the agent still wins. | | GCTRL_CODE_FOLDER | Direct mode: folder path (Users/<name>/Code) for a code graph the server auto-creates as <repo> (code). Hosts that launch the server per user (Anvil) set it so every colleague's code lands in their own folder; without it GCTRL files under the account owner's Users/<owner>/Code. |

Dev-only fallback: GCTRL_EMAIL + GCTRL_PASSWORD (full-clearance JWT). Avoid in production.

Build from source

cd borghive/services/mcpnpm installnpm run build

Working on the code indexer

gctrl-code-indexer is an optional dependency and is not on npm yet, so a plain npm install here will not fetch it. To develop or test gctrl_code_index against the in-repo package, link it once:

cd borghive/packages/code-indexer && npm ci && npm run buildcd ../../services/mcp && npm install ../../packages/code-indexer --no-save# or: npm link ../../packages/code-indexer

The server's types for the indexer are declared locally, so npm run build passes with or without the package installed - the difference is only whether gctrl_code_index works at runtime or returns its install hint.

Publish order

gctrl-mcp and gctrl-code-indexer are two npm packages and must go out in this order:

1. Publish [email protected].
2. Switch optionalDependencies in services/mcp/package.json to a real registry range (it already reads ^0.1.0; confirm it resolves) and re-run npm install.
3. Bump gctrl-mcp to 1.1.0 (package.json + package-lock.json root).
4. Publish gctrl-mcp.

Bumping gctrl-mcp BEFORE the indexer is on npm would break npx gctrl-mcp for every existing user - which is exactly why the version sits at 1.0.1 today.