<!-- mcp-tool-guidance-callout --> > [!note] > **Before picking up this work:** this issue adds an MCP tool. Please follow the [Adding a new tool](https://docs.gitlab.com/development/duo_agent_platform/mcp/#adding-a-new-tool) guidance first. That includes creating an MCP Tool Proposal, using `verb_object` naming (`get_` / `list_` / `save_` / `delete_`), and the shared resource-identification input base classes. ## Summary Add an MCP server tool (`list_groups`) that returns a list of GitLab groups and subgroups accessible to the authenticated user, so MCP clients and Duo Agent Platform agents can dynamically discover and navigate the GitLab group hierarchy without hard-coding group IDs or paths. Parent epic: https://gitlab.com/groups/gitlab-org/-/epics/20529 Related: https://gitlab.com/gitlab-org/gitlab/-/work_items/591304 (`list_projects`) --- ## Problem to solve Today, the GitLab MCP server exposes several tools (for example, `create_issue`, `get_issue`, `create_merge_request`, `get_merge_request_*`, `get_pipeline_jobs`, `search`, `semantic_code_search`, etc.), but there is **no dedicated tool to list groups or subgroups** via MCP. The `search` tool can use `scope="projects"` to search projects, but there is no equivalent for groups. For MCP-based agents and external MCP clients that orchestrate work across a GitLab organization, it is hard to: - Discover which groups and subgroups are available to the current user. - Navigate the organizational hierarchy (top-level group → subgroups → projects). - Build flows like "show me the group structure, then drill into a subgroup's projects and issues" without hard-coding group IDs or full paths. - Understand the organizational structure of a GitLab instance or namespace. This is particularly limiting for Duo Agent Platform + MCP workflows where agents should be able to reason over "my groups" or "subgroups under this parent group" in a generic way. Combined with the proposed `list_projects` tool (#591304), this would enable full hierarchy navigation: groups → subgroups → projects. --- ## Proposal Add a new MCP server tool, `list_groups`, backed by the existing `Query.groups` GraphQL query — no new API surface needed for most of this, see Resources. **Tool name** - `list_groups` **User-facing description** > List GitLab groups and subgroups accessible to the current user, optionally filtered by parent group, search term, or visibility. Useful for navigating the organizational hierarchy, discovering groups to operate on with other MCP tools, or understanding the structure of a GitLab namespace. **Input parameters** - `parent_id` (string, optional): ID or full path of a parent group to list subgroups of. If omitted, lists top-level groups accessible to the user. - `search` (string, optional): Filter by group name or path. - `visibility` (string, optional): One of `public`, `internal`, `private`. - `include_subgroups` (boolean, optional): If `true`, recursively include all descendant subgroups. Defaults to `false` (direct children only). - `first` (integer, optional, 1-100, default: 20): page size. - `after` (string, optional): cursor from the previous response's `page_info.end_cursor`. **Output** A structured list of groups, designed to be easy for agents to parse and use in follow-up calls. For each group, include at least: - `id` - `full_path` - `name` - `description` (optional) - `visibility` - `parent_id` (if a subgroup) This allows: - Duo agents and external MCP clients to show a group/namespace picker. - Follow-up tool calls (for example, `list_projects`, `search`, or future tools) to use either `id` or `full_path` directly. - Agents to build a mental model of the organizational hierarchy. **Resolved open questions** - ~~Should this tool be backed primarily by REST (`/groups`) or GraphQL?~~ GraphQL — `Query.groups` (`Resolvers::GroupsResolver` → `Resolvers::Namespaces::BaseGroupsResolver`) already covers search, parent-scoping, and cursor pagination with proper authorization; no reason to hand-roll a REST wrapper or a `Base::CustomService`. See Resources below for the two filters (`visibility`, `include_subgroups`) that need a small resolver addition first. - ~~Should we support both "global" and "parent-scoped" listing, or start with parent-scoped only?~~ Both, for free — `parent_path` is optional on the resolver already; omitting it lists top-level/all-accessible groups per `all_available`/`top_level_only`. - ~~What limits on `per_page`/total results?~~ Use cursor pagination (`first`/`after`) like the rest of the MCP tools, capped at 100 per page — not REST's `page`/`per_page`. - ~~Should `include_subgroups` be supported initially or deferred?~~ Include it — `GroupsFinder` already supports the underlying behavior (`include_parent_descendants`), it's just not exposed as a resolver argument yet (see Resources). --- ## Use cases 1. **Agent navigates the organizational hierarchy** - Agent calls `list_groups` to discover top-level groups. - User selects a group. - Agent calls `list_groups` with `parent_id` to discover subgroups. - Agent calls `list_projects` (from #591304) scoped to the selected group. - Agent then operates on the selected project with existing MCP tools. 2. **Multi-group analysis flows** - Custom agent: "Show me all groups under our organization that have 'platform' in the name." - Calls `list_groups` with `parent_id = org_group`, `search = "platform"`. - Iterates over the returned groups to perform follow-up actions (for example, list projects, aggregate issues, etc.). 3. **External MCP clients (Cursor, Claude Code, etc.)** - User connects an MCP-compatible client to the GitLab MCP server. - User asks: "What groups do I have access to?" or "Show me the subgroups under `my-org`." - Client uses `list_groups` to: - Render a group/namespace picker. - Use the selected group with other GitLab MCP tools (`list_projects`, `search`, etc.). 4. **Onboarding and discovery** - A new team member asks their AI assistant: "Help me understand how our GitLab is organized." - Agent calls `list_groups` recursively to map out the hierarchy, then summarizes the structure. --- ## Resources - Existing GraphQL query: `Query.groups` (`app/graphql/types/query_type.rb`) → `Resolvers::GroupsResolver` → `Resolvers::Namespaces::BaseGroupsResolver` (`app/graphql/resolvers/namespaces/base_groups_resolver.rb`). Already supports `search`, `parent_path`, `top_level_only`, `all_available`, cursor pagination, and authorization via `GroupType#authorize :read_group`. - Output fields all exist on `Types::GroupType` (`app/graphql/types/group_type.rb`): `id` (GID, needs unwrapping — see plan step 3), `full_path`, `name`, `description`, `visibility`, `parent { id }` (for `parent_id`). - **Gap**: `visibility`/`include_subgroups` filters aren't exposed as resolver arguments yet, even though `GroupsFinder` (`app/finders/groups_finder.rb`) already supports both underneath (`params[:visibility]`, `params[:include_parent_descendants]`). Filed `#609450` to add `visibility_level`/`include_subgroups` arguments to `BaseGroupsResolver`, mirroring the existing `visibility_level` argument on `Resolvers::ProjectsResolver` — this issue is blocked by it. - Resource resolution precedent: `Mcp::Tools::Concerns::ResourceFinder#find_parent_by_id_or_path!` (`app/services/mcp/tools/concerns/resource_finder.rb`) for resolving `parent_id` to a group's `full_path`. - Reference shape: `list_merge_requests` (`app/services/mcp/tools/merge_requests/list_merge_requests_{tool,service}.rb`) — closest existing GraphQL-backed list tool with cursor pagination. - MCP dev guidelines: `doc/development/duo_agent_platform/mcp/_index.md`; `gitlab-mcp-tool-builder` skill's build recipe — verify a GraphQL field exists before writing a custom one. - [Add list_projects MCP tool (#591304)](https://gitlab.com/gitlab-org/gitlab/-/work_items/591304) — companion issue for project listing. ## Implementation Plan 1. Two classes: `Mcp::Tools::Groups::ListGroupsTool < Mcp::Tools::Base::GraphqlTool` and `Mcp::Tools::Groups::ListGroupsService < Base::GraphqlService`. 2. Operation file: `app/graphql/queries/mcp/groups/list_groups.query.graphql`, calling `groups(parentPath:, search:, visibilityLevel:, includeSubgroups:, first:, after:)`, selecting `id`, `fullPath`, `name`, `description`, `visibility`, `parent { id }`. 3. `parent_id` → `parentPath`: resolve via `find_parent_by_id_or_path!(:group, identifier)` (from `ResourceFinder`) and pass the resolved group's `full_path` — the resolver's `parent_path` argument only accepts a path string, not a numeric id. 4. `visibility`/`include_subgroups`: pass straight through as `visibilityLevel`/`includeSubgroups` once `#609450` lands (blocks this issue). 5. `id`/`parent_id`: `GroupType#id` returns a GID (`BaseObject#id` → `GitlabSchema.id_from_object`) — unwrap the numeric id for both `id` and the nested `parent.id` in `process_result`, same pattern as the Duo Workflow tools' `workflow_id`. 6. Pagination: `first`/`after`, returning `page_info.has_next_page`/`end_cursor` from the connection's `pageInfo`. 7. Register in `GRAPHQL_TOOLS` in `app/services/mcp/tools/manager.rb`. 8. Specs: `spec/graphql/all_queries_spec.rb` coverage comes free from the committed `.graphql` file; add Tool/Service specs mirroring `list_merge_requests_{tool,service}_spec.rb` — no filter, parent filter, search filter, visibility filter, `include_subgroups`, pagination, empty result.