Ground Control (GCTRL) MCP Server

The io.github.GCTRL-TECH/gctrl MCP server exposes Ground Control’s knowledge management capabilities as MCP tools for Claude and other AI agents. It supports knowledge extraction, entity resolution, graph-native agent memory, and hybrid RAG using Neo4j and Qdrant.

🛠️ Key Features

Extract knowledge from text into Neo4j entities and Qdrant vectors (gctrl_extract)
Query knowledge graphs with hybrid RAG (gctrl_query)
Search entities by name/type (gctrl_search_entities)
List compiled knowledge graphs (gctrl_list_graphs)
Fuse extraction jobs into unified graphs (gctrl_fuse)
List available ontologies (gctrl_list_ontologies)
Scoped access tokens and “governed” graph-native agent memory

🚀 Use Cases

Knowledge extraction into knowledge graphs and vector embeddings
Question answering over entity-resolved, graph-grounded data
Entity lookup and ontology discovery for agent workflows

⚡ Developer Benefits

Integrates MCP tooling for Claude/agents
Supports hybrid RAG across structured graph data and vector search
Enables graph compilation browsing, entity search, and graph fusion steps

⚠️ Limitations

Tool coverage is limited to the listed MCP tools: extract, query, entity search, list graphs, fuse, and list ontologies.

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, …):

json

{
  "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:

json

{
  "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

bash

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:

bash

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:

Publish gctrl-code-indexer@0.1.0.
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.
Bump gctrl-mcp to 1.1.0 (package.json + package-lock.json root).
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.

io.github.GCTRL-TECH/gctrl