Connect via MCP

Tier: Premium, Ultimate
Offering: GitLab.com
Status: Experiment

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

Orbit exposes two MCP tools that let any MCP-compatible AI agent query your GitLab knowledge graph. Use this with Claude Code, OpenAI Codex, or any other tool that supports the Model Context Protocol.

Prerequisites

Orbit is enabled on your group.
You’re authenticated to GitLab. Run glab auth login (uses OAuth by default; personal access tokens with read_api scope also work).
Your auth has access to the groups you want to query.

MCP tools

Tool	Description
`query_graph`	Execute a graph query using the Orbit query DSL. Returns typed results.
`get_graph_schema`	Fetch the current schema: all node types, their properties, and relationship types.

Connect your MCP client

Configure your MCP client to point at https://gitlab.com/api/v4/orbit/mcp.

Claude Code supports the Orbit endpoint over the built-in HTTP transport. Register it with one command:

claude mcp add --transport http gitlab-orbit https://gitlab.com/api/v4/orbit/mcp

The first query_graph or get_graph_schema call opens your browser to authenticate with GitLab. No JSON config edit required.

Some clients only support local stdio MCP servers. For those, mcp-remote wraps the Orbit endpoint as a local command.

Cursor, Codex, and other JSON-config clients — add to your agent’s MCP config:

{
  "mcpServers": {
    "gitlab-orbit": {
      "command": "npx",
      "args": ["mcp-remote", "https://gitlab.com/api/v4/orbit/mcp"]
    }
  }
}

opencode — add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "gitlab-orbit": {
      "type": "local",
      "command": ["npx", "mcp-remote", "https://gitlab.com/api/v4/orbit/mcp"]
    }
  }
}

opencode requires "type": "local" and places command and arguments together in a single array. Using a separate args field or omitting type causes a ConfigInvalidError.

Authentication uses your existing glab auth login session - no token to copy or paste. Supported clients: Claude Code, OpenCode, Cursor, Codex, Gemini CLI.

A planned glab orbit setup subcommand will install the Orbit skill and write this MCP config in one step. Until it ships, configure your MCP client manually as shown above.

Test it

In your AI agent, ask:

“Use Orbit to list the 5 most recently updated projects in my group.”

You should get typed results back with project names and paths. If you do, you’re connected. If not, run glab auth status to confirm you’re authenticated, and check that Orbit is enabled on at least one of your groups.

Billing

Queries through MCP consume GitLab Credits. Each query call to query_graph uses credits from your GitLab subscription. get_graph_schema calls are free.

Using the tools

Once connected, instruct your AI agent to use the Orbit tools directly:

Discover the schema:

“Use get_graph_schema to show me what node types Orbit indexes.”

Run a query:

“Use query_graph to find the 10 projects with the most open merge requests in the gitlab-org group.”

Blast radius analysis:

“Use Orbit to find all files in this project that import AuthService directly or transitively.”

Onboarding:

“Use Orbit to map the key services in this group, their languages, and which projects they depend on.”

The agent composes the JSON query DSL and calls query_graph on your behalf. You can also pass raw JSON queries directly if you want precise control over results.

Example: manual query_graph call

{
  "query_type": "aggregation",
  "nodes": [
    {"id": "p", "entity": "Project", "columns": ["name", "full_path"]},
    {"id": "mr", "entity": "MergeRequest", "filters": {"state": "opened"}}
  ],
  "relationships": [
    {"type": "IN_PROJECT", "from": "mr", "to": "p"}
  ],
  "group_by": [{"kind": "node", "node": "p"}],
  "aggregations": [
    {"function": "count", "target": "mr", "alias": "open_mrs"}
  ],
  "aggregation_sort": {"column": "open_mrs", "direction": "DESC"},
  "limit": 10
}