Orbit

Orbit exposes GitLab.com’s experimental Knowledge Graph API through six read-only MCP tools. It is available only when the server connects to https://gitlab.com and the Enterprise/Premium catalog is enabled with GITLAB_ENTERPRISE=true or --enterprise.

Technical reference

For the complete generated tool reference, see docs/tools/orbit.md in the repository.

Availability

Requirement	Value
GitLab host	https://gitlab.com
Catalog	Enterprise/Premium
Meta-tool mode	gitlab_orbit with six actions
Individual mode	Six gitlab_orbit_* tools
Write behavior	Read-only

Self-managed GitLab instances do not register Orbit tools, even when the Enterprise/Premium catalog is enabled.

Actions

Action	Individual tool	Purpose
status	gitlab_orbit_status	Check Orbit service health and component status
schema	gitlab_orbit_schema	Inspect the graph ontology and optionally expand node definitions
tools	gitlab_orbit_tools	Discover the live Orbit query manifest
dsl	gitlab_orbit_dsl	Retrieve the Orbit query DSL schema or LLM grammar
query	gitlab_orbit_query	Execute a read-only Knowledge Graph query object
graph_status	gitlab_orbit_graph_status	Inspect indexing status for a namespace, project, or full path

Typical flow

1. Call gitlab_orbit with action: "status" to confirm the service is available.
2. Call action: "schema" to inspect graph domains, nodes, and relationships.
3. Call action: "tools" before action: "query" to obtain the live query schema served by GitLab.com.
4. (Optional) Call action: "dsl" to retrieve the Orbit query DSL schema or LLM grammar.
5. Pass a JSON query object to action: "query" with response_format set to raw or llm.

Query DSL variants

The query parameter on the query action is a JSON object whose query_type selects one of four variants. The diagram below summarizes the smallest accepted shape for each variant. A Mermaid graph TD is the right tool because the four variants share a single query_type discriminator and only diverge on the sibling keys — a tree makes the discriminants and required fields legible at a glance.

graph TD
    Q["QueryInput<br/>(gitlab_orbit_query)"] --> QT{"query_type"}
    QT -->|"traversal"| TR["node OR nodes<br/>+ entity, node_ids/filters/id_range<br/>+ relationships?, columns?, order_by?, limit?, cursor?"]
    QT -->|"aggregation"| AG["nodes[]<br/>+ aggregations[] (function, target, alias)<br/>+ group_by?, aggregation_sort?"]
    QT -->|"neighbors"| NB["node (bounded)<br/>+ neighbors.node<br/>+ direction?, rel_types?"]
    QT -->|"path_finding"| PF["nodes[] (>=2, bounded)<br/>+ path {type, from, to, max_depth: 1..3, rel_types?}"]

Discover → query workflow

The recommended pattern is to discover the live schema first (schema, then optionally dsl), then execute a typed query through query. A sequenceDiagram is the right tool because the steps involve four distinct actors (AI client, MCP server, GitLab.com, the Orbit indexer) and the response boundaries matter — the LLM should not assume the schema returned by dsl is stable.

sequenceDiagram
    participant LLM as AI Client
    participant MCP as MCP Server
    participant GL as GitLab.com API
    participant IDX as Orbit Indexer

    LLM->>MCP: gitlab_orbit_schema (response_format=llm)
    MCP->>GL: GET /api/v4/orbit/schema
    GL-->>MCP: ontology (nodes, edges, versions)
    MCP-->>LLM: schema text

    LLM->>MCP: gitlab_orbit_dsl (response_format=llm)
    MCP->>GL: GET /api/v4/orbit/schema/dsl
    GL-->>MCP: query DSL / LLM grammar
    MCP-->>LLM: DSL text

    LLM->>MCP: gitlab_orbit_query (query={query_type, ...})
    MCP->>GL: POST /api/v4/orbit/query
    GL->>IDX: resolve node_ids / filters
    IDX-->>GL: indexed rows
    GL-->>MCP: rows / aggregations / paths
    MCP-->>LLM: result + markdown

Example: Check Orbit status

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "status"
  }
}

Example: Get graph schema

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "schema",
    "params": {
      "expand": ["Project", "User"],
      "response_format": "llm"
    }
  }
}

Example: Get Orbit tool manifest

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "tools"
  }
}

Example: Get Orbit query DSL

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "dsl",
    "params": {
      "response_format": "llm"
    }
  }
}

Example: Run a Knowledge Graph query

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "query",
    "params": {
      "query": {
        "query_type": "traversal",
        "node": {
          "id": "p",
          "entity": "Project",
          "filters": {
            "full_path": { "op": "starts_with", "value": "gitlab-org/" }
          },
          "columns": ["id", "full_path"]
        }
      },
      "response_format": "llm"
    }
  }
}

Example: Check indexing status

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "graph_status",
    "params": {
      "project_id": 278964,
      "response_format": "llm"
    }
  }
}

Action details

status — Check Orbit service health

Returns cluster health and backend component status. Use to verify Orbit is available for your token and project.

Example: See above.

schema — Inspect the graph ontology

Returns the Orbit graph ontology, including schema version, domains, node summaries, and edges. Use expand to get detailed node definitions. Supports response_format (raw or llm).

Example: See above.

tools — Discover the Orbit tool manifest

Returns the live Orbit MCP tool manifest. Use before query to discover supported query shapes and parameter schemas.

Example: See above.

dsl — Retrieve the Orbit query DSL schema or LLM grammar

Returns the Orbit query DSL as a JSON Schema (raw) or LLM grammar (llm). Useful for advanced query construction and LLM integration.

Example: See above.

query — Execute a Knowledge Graph query

Runs a read-only Knowledge Graph query. The query parameter must match the schema from tools. Supports response_format (raw or llm).

Example: See above.

graph_status — Inspect indexing status

Returns graph indexing status for a namespace, project, or full path. Use to check if a project is indexed and ready for queries.

Example: See above.

Schema discovery

In meta-tool mode, action parameter schemas are available through MCP resources:

Resource	Purpose
gitlab://tools/gitlab_orbit.status	Parameters for service health checks
gitlab://tools/gitlab_orbit.schema	Parameters for ontology inspection
gitlab://tools/gitlab_orbit.tools	Parameters for query manifest discovery
gitlab://tools/gitlab_orbit.dsl	Parameters for DSL schema/grammar
gitlab://tools/gitlab_orbit.query	Parameters for Knowledge Graph queries
gitlab://tools/gitlab_orbit.graph_status	Parameters for indexing status checks

These resources remain available with CAPABILITY_SURFACE=full or minimal, regardless of META_PARAM_SCHEMA mode.

Run the live tests

Orbit ships with a build-tag-gated live test suite at test/e2e/orbit/live_test.go that exercises each handler against the real https://gitlab.com/api/v4/orbit/* endpoints. The suite has four entry points and 41 subtests covering all six handlers, the canonical Query DSL shapes, fixture-based smoke tests, and the full DSL feature surface. The orchestrator make test-e2e-gitlab-com provisions kg-fixtures and security-fixtures projects in your namespace (idempotent), waits for the Orbit indexer to catch up, then runs the tests:

# Add a Personal Access Token (api scope) to .env first
echo 'GITLAB_COM_TOKEN=glpat-...' >> .env

# Default namespace is plens1; override with ORBIT_FIXTURES_NAMESPACE
make test-e2e-gitlab-com ORBIT_FIXTURES_NAMESPACE=acme-research

# When fixtures are already provisioned, run only the tests
GITLAB_COM_TOKEN=glpat-... \
  go test -tags orbitlive -count=1 -v -timeout 300s ./test/e2e/orbit/

See Orbit live test fixtures for the fixture layout, the scripts/setup-orbit-fixtures.sh reproducer, and the indexer caveat (transient error state is normal and the tests are informational, not strict equality).