Orbit knowledge graph

Orbit is GitLab.com’s experimental knowledge graph of code and project data. Its six actions are served only to a session connected to GitLab.com at Premium or Ultimate, and all of them read: orbit.status checks the service, orbit.schema describes the graph, orbit.dsl serves the query language, orbit.query runs a query, orbit.tools lists Orbit’s own MCP tools, and orbit.graph_status reports the indexing of a namespace or a project. GitLab answers 404 while its knowledge_graph feature flag is off for the caller. The Orbit page explains the workflow.

Sample questions

• “Is Orbit available for this GitLab.com token?”
• “Show the knowledge graph schema”
• “Has gitlab-org/gitlab finished indexing?”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as orbit.dsl, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
• Meta (GITLAB_MCP_TOOL_SURFACE=meta): call gitlab_orbit with action set to the action’s name, such as dsl, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_orbit_dsl, with its parameters as the arguments.

Availability

How many of these actions an instance serves at each tier, out of a total of 6:

• Free: 0
• Premium: 0 on a self-managed instance, 6 on GitLab.com
• Ultimate: 0 on a self-managed instance, 6 on GitLab.com

Read-only actions: 6 of 6, the ones a deployment in read-only mode keeps.

Actions

The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served.

Action	Individual
orbit.dsl	gitlab_orbit_dsl
orbit.graph_status	gitlab_orbit_graph_status
orbit.query	gitlab_orbit_query
orbit.schema	gitlab_orbit_schema
orbit.status	gitlab_orbit_status
orbit.tools	gitlab_orbit_tools

orbit.dsl

Retrieve the GitLab Orbit (Knowledge Graph) query DSL schema or LLM grammar.

• Meta-tool: gitlab_orbit, action dsl
• Individual tool: gitlab_orbit_dsl
• Tier: Premium, GitLab.com only
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
response_format	string	no	Response format: raw or llm (json is read as raw). When omitted, the GitLab default (raw) applies.

orbit.graph_status

Inspect GitLab Orbit (Knowledge Graph) indexing status for one namespace, project, or full_path.

• Meta-tool: gitlab_orbit, action graph_status
• Individual tool: gitlab_orbit_graph_status
• Tier: Premium, GitLab.com only
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
full_path	string	no	Full path of a group or project to inspect, for example gitlab-org/gitlab. Set exactly one scope field.
namespace_id	integer	no	Namespace/group ID to inspect. Set exactly one of namespace_id, project_id, or full_path.
project_id	integer	no	Project ID to inspect. Set exactly one of namespace_id, project_id, or full_path.
response_format	string	no	Response format: raw or llm (json is read as raw). When omitted, the GitLab default (raw) applies.

orbit.query

Execute a read-only GitLab Orbit (Knowledge Graph) query in the version 12 DSL orbit.dsl serves, naming the entities and relationship types orbit.schema lists. Every query has a query_type (traversal, aggregation, neighbors, or path_finding) and lists its nodes in a nodes array, and a refused query is corrected from the message GitLab answers with.

• Meta-tool: gitlab_orbit, action query
• Individual tool: gitlab_orbit_query
• Tier: Premium, GitLab.com only
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
query	object	yes	Orbit query in the version 12 DSL that orbit.dsl serves, as a JSON object. Required: query_type (traversal, aggregation, neighbors or path_finding) and nodes, a list of node selectors {id, entity, columns, filters, node_ids, id_range} even for one node. A filter is a bare value for equality or an object keyed by operators such as {“starts_with”: “gitlab-org/”}, never {op, value}. A traversal or aggregation query needs node_ids or filters on a node. A neighbors query takes one node and neighbors {direction, rel_types}, where direction defaults to outgoing (pass both for every relationship). A path_finding query takes two nodes and path {type: shortest, from, to, max_depth 1 to 3, rel_types} with rel_types required (* for any). Aggregations are {count: “mr”, as: “n”}, order_by is “node.property” (“-node.property” descending). orbit.schema lists the entities, properties and relationship types. GitLab refuses a query it cannot compile with a message naming the fault.
response_format	string	no	Response format: raw or llm (json is read as raw). When omitted, the GitLab default (raw) applies.

orbit.schema

Inspect the GitLab Orbit (Knowledge Graph) ontology: domains, node types, edge types.

• Meta-tool: gitlab_orbit, action schema
• Individual tool: gitlab_orbit_schema
• Tier: Premium, GitLab.com only
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
expand	string[]	no	Node names to expand with full properties and relationships.
format	string	no	Schema response format: raw or llm (json is read as raw). When omitted, the GitLab default (raw) applies.
response_format	string	no	Alias for format. Must match format when both are set.

orbit.status

Inspect GitLab Orbit (Knowledge Graph) cluster health on GitLab.com.

• Meta-tool: gitlab_orbit, action status
• Individual tool: gitlab_orbit_status
• Tier: Premium, GitLab.com only
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
response_format	string	no	Response format: raw or llm (json is read as raw). When omitted, the GitLab default (raw) applies.

orbit.tools

List the GitLab Orbit (Knowledge Graph) MCP tool manifest and parameter schemas.

• Meta-tool: gitlab_orbit, action tools
• Individual tool: gitlab_orbit_tools
• Tier: Premium, GitLab.com only
• Behavior: read-only, idempotent

No parameters.