MCPを使用してOrbitにアクセスする

GitLab OrbitはMCP対応のAIエージェントがGitLabのナレッジグラフに対してGitLab Orbitコマンドを検出・実行できる2つのMCPツールを公開しています。Claude Code、OpenAI Codex、またはModel Context Protocolをサポートするその他のツールと組み合わせて使用できます。

前提条件

• GitLab Orbitがグループで有効化されていること。
• GitLabに認証済みであること。glab auth loginを実行してください（デフォルトではOAuthを使用。read_apiスコープを持つパーソナルアクセストークンも使用可能）。
• クエリ対象のグループへのアクセス権限があること。
• MCPクライアントが（mcp-remoteを経由せず）ネイティブHTTPで直接接続する場合、OAuthリクエストにmcp_orbitスコープを含める必要があります。以下のGemini CLIの例を参照してください。

MCPツール

invoke_commandで利用可能なコマンド:

MCPクライアントを接続する

MCPクライアントがhttps://gitlab.com/api/v4/orbit/mcpを指すように設定します。

Claude Codeは組み込みのHTTPトランスポートを使用してOrbitエンドポイントをサポートしています。 次のコマンドで登録します:

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

最初のlist_commandsまたはinvoke_commandの呼び出し時にブラウザが開き、GitLabで認証が行われます。JSONの設定ファイルを編集する必要はありません。

一部のクライアントはローカルのstdio MCPサーバーのみをサポートしています。そのような場合は、mcp-remoteを使用してOrbitエンドポイントをローカルコマンドとしてラップします。

Cursor、Codex、およびその他のJSON設定クライアント — エージェントのMCP設定に以下を追加します:

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

opencode — ~/.config/opencode/opencode.jsonに以下を追加します:

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

Gemini CLI — ネイティブHTTPトランスポートでOrbitエンドポイントをサポートしています。~/.gemini/settings.jsonに以下を追加します:

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

gemini mcp add gitlab-orbit https://gitlab.com/api/v4/orbit/mcp -t http -s userで生成した後、oauth.scopesブロックを手動で追加することもできます。

Antigravity — Antigravity IDEとCLIは~/.gemini/config/mcp_config.jsonにある同じMCP設定を読み込みます。Antigravityはリモートサーバーに対するMCP OAuthフローをまだサポートしていないため（ネイティブのserverUrlエントリはトークンなしでinitializeを送信し、Unauthorizedで失敗します）、mcp-remoteでエンドポイントをラップします:

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

認証には既存のglab auth loginセッションを使用します。トークンのコピーや貼り付けは不要です。サポートされているクライアント: Claude Code、OpenCode、Cursor、Codex、Gemini CLI、Antigravity。

また、GitLab Orbitスキルを手動でインストールすることで、エージェントにクエリレシピ、DSLガイダンス、トラブルシューティング情報を提供できます。

動作確認

AIエージェントで次のように質問します:

「Orbitを使用して、グループ内で最近更新された5つのプロジェクトを一覧表示してください。」

プロジェクト名とパスを含む型付きの結果が返されれば、接続は成功しています。結果が返されない場合は、glab auth statusを実行して認証状態を確認し、少なくとも1つのグループでGitLab Orbitが有効になっていることを確認してください。

課金

MCP経由のクエリはGitLabクレジットを消費します。query_graphを実行するinvoke_commandの呼び出しはGitLabサブスクリプションのクレジットを使用します。list_commands、get_graph_schema、get_query_dsl、get_response_formatコマンドは消費対象外です。

ツールの使用方法

接続後、AIエージェントにGitLab Orbitツールを直接使用するよう指示します:

コマンドとスキーマの確認:

「list_commandsを使用して利用可能なGitLab Orbitコマンドを表示し、次にget_graph_schemaコマンドを実行してGitLab Orbitがインデックス作成するノードタイプを確認してください。」

クエリの実行:

「query_graphコマンドを使用して、グループ内でオープンなマージリクエストが最も多い10件のプロジェクトを検索してください。」

影響範囲の分析:

「Orbitを使用して、このプロジェクト内でAuthServiceを直接または推移的にインポートしているすべてのファイルを検索してください。」

オンボーディング:

「Orbitを使用して、このグループの主要なサービス、使用言語、および依存プロジェクトをマップしてください。」

エージェントはJSONクエリDSLを構成し、代わりにquery_graphコマンドを呼び出します。結果を正確に制御したい場合は、生のJSONクエリを直接渡すこともできます。

例: invoke_commandによるquery_graphの手動呼び出し

以下のクエリをinvoke_commandに{"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
}

トラブルシューティング

Claude Codeで「Failed to connect」が表示される

Claude Codeには組み込みのHTTP MCPサポートがあります。--transport httpの代わりにnpx mcp-remoteでOrbitを登録した場合、mcp-remoteラッパーがローカルのstdioプロセスを作成し、ネイティブトランスポートと競合します。

修正するには、壊れた登録を削除してHTTPトランスポートで再登録します:

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

初回使用時に「Needs authentication」が表示される

これは想定された動作です。最初のlist_commandsまたはinvoke_commandの呼び出し時にブラウザが開き、GitLabでOAuth認証が完了します。ブラウザフローが起動しない場合は、セッションを確認してください:

glab auth status

セッションが期限切れの場合は、再認証してください:

glab auth login

接続後のクエリエラー

クエリ時のエラー（検証の失敗、空の結果、レート制限）については、DSLガイダンス、クエリレシピ、終了コードの診断情報が含まれるGitLab Orbitスキルのドキュメントを参照してください。インラインガイダンスのためにスキルをインストールします:

glab skills install --global orbit