Connect via MCP

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

Prerequisites

• GitLab Orbit is enabled on your group.
• You’re authenticated to GitLab. Run glab auth login. This command uses OAuth authentication by default. Alternatively, you can use either a fine-grained personal access token or a personal access token with the scope set to read_api.
• Your auth has access to the groups you want to query.
• If your MCP client connects directly over native HTTP (not through mcp-remote), its OAuth request must include the mcp_orbit scope. See the Gemini CLI example below.

MCP tools

Commands available through invoke_command:

The default-off Rails orbit_gql_queries feature flag selects one mode per user. See the GQL access requirements. With the flag off, list_commands teaches JSON and query_graph accepts only JSON objects. With the flag on, discovery teaches only GQL and query_graph accepts only strings. The catalog hides get_query_dsl, and direct or invoked DSL requests reject. Use CALL db.schema() for graph discovery instead. Clients cannot select a language, and discovery results must not be shared across users or modes.

Connect your MCP client

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

Claude Code supports the GitLab 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 list_commands or invoke_command 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 GitLab 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"]
    }
  }
}

Gemini CLI — supports the GitLab Orbit endpoint over native HTTP transport. Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "gitlab-orbit": {
      "url": "https://gitlab.com/api/v4/orbit/mcp",
      "type": "http",
      "timeout": 5000,
      "oauth": {
        "enabled": true,
        "scopes": ["mcp_orbit"]
      }
    }
  }
}

You can also generate this with gemini mcp add gitlab-orbit https://gitlab.com/api/v4/orbit/mcp -t http -s user, then add the oauth.scopes block by hand.

Antigravity — the Antigravity IDE and CLI read the same MCP config at ~/.gemini/config/mcp_config.json. Antigravity does not yet run the MCP OAuth flow for remote servers (a native serverUrl entry sends initialize without a token and fails with Unauthorized), so wrap the endpoint with mcp-remote:

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

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

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

Test it

In your AI agent, ask:

“Use GitLab 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 GitLab Orbit is enabled on at least one of your groups.

Billing

During the beta, queries through MCP do not consume GitLab Credits.

When GitLab Orbit is generally available, each invoke_command call that runs query_graph consumes GitLab Credits from your subscription. list_commands and the get_graph_schema, get_query_dsl, and get_response_format commands stay free. Credit rates are published in GitLab Credits and usage billing before charging begins.

Using the tools

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

Discover the commands and schema:

“Use list_commands to show me what GitLab Orbit commands are available, then run the get_graph_schema command to show me what node types GitLab Orbit indexes.”

Run a query:

“Use the query_graph command to find the 10 projects with the most open merge requests in your group.”

Blast radius analysis:

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

Onboarding:

“Use GitLab 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 invokes the query_graph command on your behalf. You can also pass raw JSON queries directly if you want precise control over results.

Example: manual invoke_command call for query_graph

Pass the query below as invoke_command with {"command_name": "query_graph", "parameters": {"query": ...}}:

{
  "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": ["p"],
  "aggregations": [
    { "count": "mr", "as": "open_mrs" }
  ],
  "aggregation_sort": "-open_mrs",
  "limit": 10
}

Troubleshooting

“Failed to connect” in Claude Code

Claude Code has built-in HTTP MCP support. If you registered GitLab 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 list_commands or invoke_command 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 GitLab Orbit skill documentation, which includes DSL guidance, query recipes, and exit-code diagnostics. Install the skill for inline guidance:

glab skills install --global orbit