<!-- 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 (for example, `list_projects`) that returns a list of GitLab projects accessible to the authenticated user, so MCP clients and Duo Agent Platform agents can dynamically discover projects without hard-coding project IDs or paths. Parent epic: https://gitlab.com/groups/gitlab-org/-/epics/20529 --- ## 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 projects** via MCP. The `search` tool can use `scope="projects"` to search projects, but: - It requires a search term. - It is not a simple “list all projects I can work with” primitive. - It is awkward for agents that need a generic “show me my projects / projects under this group” capability. For MCP-based agents and external MCP clients that orchestrate work across multiple GitLab projects, it is hard to: - Discover which projects are available to the current user. - Present a selectable list of projects to the end user. - Build flows like “select a project, then list issues / pipelines / run searches for that project” without hard-coding project IDs or full paths. This is particularly limiting for Duo Agent Platform + MCP workflows where agents should be able to reason over “my projects” or “projects under a given group” in a generic way. --- ## Proposal Add a new MCP server tool, tentatively named `list_projects`, exposed by the GitLab MCP server. **Tool name** - `list_projects` **User-facing description (suggested)** > List GitLab projects accessible to the current user, optionally filtered by group, search term, visibility, or archived flag. > Useful for presenting a project picker to the user or for discovering projects to operate on with other MCP tools. **Backing API:** build as `Base::GraphqlTool` + `Base::GraphqlService` on `Query.projects` (`Resolvers::ProjectsResolver`). The resolver covers every requested filter: `search`, `membership: true` ("my projects"), `namespace_path` (the `group_id` param, group/user full-path scoping), `visibility_level` (`VisibilityLevelsEnum`), `archived` (`Projects::ArchivedEnum`), plus `min_access_level`/`topics`/`sort`. It supports both global ("all accessible") and group-scoped listing. Returns a `ProjectType` connection (`id`, `fullPath`, `name`, `description`, `visibility`, `archived`), with cursor pagination (`first`/`after`). **Input parameters** - `group_id` (string, optional): ID or full path of a group to scope the project list. - `search` (string, optional): Filter by project name or path. - `visibility` (string, optional): One of `public`, `internal`, `private`. - `archived` (boolean, optional): Filter by archived state. - `after` (string, optional): Cursor for pagination (GraphQL `after`); page size via `first`. (`group_id` maps to `namespace_path`, `visibility` to `visibility_level`; follow `Query.projects` conventions.) **Output** A structured list of projects, designed to be easy for agents to parse and use in follow-up calls. For each project, include at least: - `id` - `full_path` - `name` - `description` (optional) - `visibility` - `archived` This allows: - Duo agents and external MCP clients to show a project picker. - Follow-up tool calls (for example, `search`, `semantic_code_search`, or future tools) to use either `id` or `full_path` directly. **Resolved** - Backed by **GraphQL** (`Query.projects`), not REST — see Backing API above. - Support **both** global and group-scoped listing; `Query.projects` handles both (pass `namespace_path` or not), so no need to start group-only. **Open question for the team** - What page-size cap (`first`) do we want to protect performance on large instances? --- ## Use cases 1. **Agent prompts user to select a project** - Agent calls `list_projects` with optional `group_id`. - Presents a list of candidate projects to the user (name + path). - User selects one project. - Agent then: - Lists issues via existing or future tools, and/or - Uses other MCP tools (`search`, `semantic_code_search`, etc.) scoped to the selected project. 2. **Multi-project analysis flows** - Custom agent: “Show me all active projects under group X with ‘billing’ in the name.” - Calls `list_projects` with `group_id = X`, `search = "billing"`, and `archived = false`. - Iterates over the returned projects to perform follow-up actions (for example, list issues, analyze pipelines, etc.). 3. **External MCP clients (Cursor, Claude Code, etc.)** - User connects an MCP-compatible client to the GitLab MCP server. - User asks: “Which GitLab projects can you see?” or “List projects under group `foo/bar`.” - Client uses `list_projects` to: - Render a project picker. - Use the selected project with other GitLab MCP tools. --- ## Sources - [GitLab MCP server tools | GitLab Docs](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server_tools/) - [GitLab MCP server | GitLab Docs](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/) - [Model Context Protocol integration](https://about.gitlab.com/blog/duo-agent-platform-with-mcp/)