Connect via MCP

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

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.

Claude Code connects directly over HTTP. Do not use npx mcp-remote with Claude Code — it wraps the endpoint in a stdio process that conflicts with the built-in transport and causes “Failed to connect” errors. Use the claude mcp add --transport http command shown above instead.

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.

You can also install the Orbit skill manually today to give the agent query recipes, DSL guidance, and troubleshooting.

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 your 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
}

Troubleshooting

“Failed to connect” in Claude Code

Claude Code has built-in HTTP MCP support. If you registered Orbit with npx mcp-remote instead of --transport http, the mcp-remote wrapper creates a local stdio process that conflicts with the native transport.

To fix, remove the broken registration and re-add with HTTP transport:

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

“Needs authentication” on first use

This is expected. The first query_graph or get_graph_schema call opens your browser to complete OAuth with GitLab. If the browser flow does not trigger, verify your session:

glab auth status

If your session is expired, re-authenticate:

glab auth login

Query errors after connecting

For query-time errors (validation failures, empty results, rate limits), see the Orbit skill documentation, which includes DSL guidance, query recipes, and exit-code diagnostics. Install the skill for inline guidance:

glab skills install --global orbit