gctrl

Ground Control (GCTRL) MCP Server

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

Tools Available

Tool	Description
gctrl_extract	Extract knowledge from text → Neo4j entities + Qdrant vectors
gctrl_query	Ask questions about knowledge graphs (hybrid RAG)
gctrl_search_entities	Search for specific entities by name/type
gctrl_list_graphs	List all knowledge graph compilations
gctrl_fuse	Merge extraction jobs into unified graphs
gctrl_list_ontologies	List available ontologies
gctrl_list_extractions	List recent extraction jobs
gctrl_store	Store knowledge (like Obsidian notes, but with KG extraction)
gctrl_schema	Get the knowledge graph schema
gctrl_code_index	Index a local repo into a Codebase KB (compilation type CODE). Direct mode only (it indexes THIS machine, so a gateway cannot serve it) and needs the optional gctrl-code-indexer package - without it the tool returns an install hint and every other tool keeps working.
gctrl_code_symbol	Find code symbols by name/path/regex (proxied to the HTTP gateway)
gctrl_code_trace	Trace callers/callees of a symbol (proxied to the HTTP gateway)
gctrl_code_impact	Impact analysis for changed symbols/files (proxied to the HTTP gateway)
gctrl_code_architecture	Languages, hotspots, communities for a Codebase KB (proxied to the HTTP gateway)

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.

Deprecated alias	Use instead
borghive_extract	gctrl_extract
borghive_query	gctrl_query
borghive_store	gctrl_store
borghive_fuse	gctrl_fuse
borghive_search_entities	gctrl_search_entities
borghive_list_graphs	gctrl_list_graphs
borghive_list_ontologies	gctrl_list_ontologies
borghive_list_extractions	gctrl_list_extractions
borghive_schema	gctrl_schema

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

Env var	Purpose
GCTRL_GATEWAY_URL	Recommended: URL of your harness's MCP gateway (http://<host>:4000/api/agent/mcp). The stdio server acts as a thin authenticated proxy.
GCTRL_API_URL	Alternative direct mode: GCTRL API base URL (http://<host>:4000/api); tools run locally against the API.
GCTRL_API_TOKEN	Scoped GCTRL Access Token (gctrl_…), created in Settings → Access Control with a clearance level + per-graph grants. Least privilege — the agent sees exactly what the token is cleared for.
GCTRL_MCP_TOOLS	Optional tool-set filter. Set to code to register only the local code tools (gctrl_code_index, gctrl_code_symbol, gctrl_code_trace, gctrl_code_impact, gctrl_code_architecture) — used for the Anvil/Hermes gctrl-code stdio entry, kept separate from the HTTP-gateway gctrl/gctrl-projekt entries. Direct mode only: in gateway mode the gateway's own tool list is proxied verbatim, so the filter has no effect and the server says so on startup.

| 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/mcp
npm install
npm 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 build
cd ../../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.