Implement save_project MCP Tool and service (create projects, incl. group namespace)

Note

Before picking up this work: this issue adds an MCP tool. Please follow the 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.

Release notes

Add a save_project MCP tool so agents can create GitLab projects without manual user intervention.

Problem to solve

Agentic Chat in the GitLab UI works great for many creation workflows — issues, epics, MRs, etc.

When invoked from a group namespace and asked to scaffold a new application, the agent:

  1. Creates work items on the group level (epics) to track tasks.
  2. Concludes it needs to create a GitLab project first — only then can it create branches, commits, and MRs.
  3. Fails because no tool exists to create projects.
  4. Sometimes hallucinates a workaround (copy-paste source code, bootstrap via API script), which is confusing when the agent can already create issues, epics, and MRs.

Proposal

Add an MCP server tool save_project that creates a GitLab project, so an agent invoked from a group namespace can scaffold a new project before creating branches, commits, and MRs.

Backing API: REST POST /projects. There is no GraphQL project-create mutation, so REST is correct here. allow_mcp_access_create is already declared on API::Projects, so MCP token access for POST is already enabled.

Input parameters:

Parameter Type Required Notes
name string yes (at least one of name/path) Human-readable project name
path string yes (at least one of name/path) Repository path slug
namespace_id string no Numeric ID or full path of a group or personal namespace. Defaults to the authenticated user's namespace.
description string no
visibility string no private, internal, or public
initialize_with_readme boolean no
default_branch string no
topics array of strings no
template_name string no Built-in template, e.g. rails, spring, express
template_project_id integer no Custom/group project template ID
use_custom_template boolean no EE only. Required when using template_project_id
group_with_project_templates_id integer no EE only. Group that owns the custom template

Expose only the parameters above. Do not expose import, CI/CD catalog, or admin-only params.

Limitations:

  1. Permissions — only group owners/maintainers can create projects in a group namespace.
  2. Consider compliance needs (ability to turn the tool off via governance rules) in the design.

Intended users

Anyone who wants to start a new project from an agent workflow.

Implementation plan

This is a REST-backed aggregated tool following the same pattern as save_merge_request. The implementation has three parts: the service class, the route_setting :mcp annotation on the Grape route, and specs.

1. Read these files first

Before writing any code, read these files to understand the patterns:

  • app/services/mcp/tools/merge_requests/save_merge_request_service.rb — closest analogue: a write tool that wraps a REST route via Base::AggregatedService
  • app/services/mcp/tools/projects/get_project_tool.rb and get_project_service.rb — the existing projects module structure
  • app/services/mcp/tools/base/api_service.rb and api_tool.rb — the REST base classes
  • lib/api/projects.rb — the POST /projects route (around line 494) and the allow_mcp_access_create declaration at the top
  • doc/development/duo_agent_platform/mcp/_index.md — full tool development guidelines

2. Annotate the Grape route

In lib/api/projects.rb, add a route_setting :mcp to the post route for project creation (the one without a path segment, around line 494):

route_setting :mcp,
  tool_name: :create_project,
  params: Helpers::ProjectsHelpers.create_project_mcp_params,
  resource_name: 'project',
  aggregators: [::Mcp::Tools::Projects::SaveProjectService]

Define create_project_mcp_params in lib/api/helpers/projects_helpers.rb with the CE params, and override it in ee/lib/ee/api/helpers/projects_helpers.rb as [*super, :use_custom_template, :group_with_project_templates_id]. create_issue_mcp_params in lib/api/helpers/issues_helpers.rb and its EE override follow the same pattern.

allow_mcp_access_create is already declared on the API::Projects class, so no additional access declaration is needed.

3. Create the service class

Create app/services/mcp/tools/projects/save_project_service.rb. Model it on save_merge_request_service.rb but simpler — this tool is create-only (no update path), so no operation detection is needed.

Key points:

  • Inherit from Mcp::Tools::Base::AggregatedService
  • tool_name → 'save_project'
  • toolset → :core
  • annotations → { readOnlyHint: false, destructiveHint: false }
  • required → [] (both name and path are optional individually; the API enforces at_least_one_of). Say "provide name, path, or both" in the tool description.
  • In select_tool, find the :create_project tool from tools
  • In transform_arguments, resolve a full-path namespace_id to its numeric ID before forwarding. POST /projects only accepts an integer.
  • Override self.namespace_arguments to declare { group: :namespace_id } so governance rules apply when a group namespace is targeted. Calls that target a personal namespace, or omit namespace_id, resolve no group and are not governed.
  • Keep input_schema to CE params and add prepend_mod. Add the two EE template params in ee/app/services/ee/mcp/tools/projects/save_project_service.rb by overriding input_schema with super.deep_merge(properties: { ... }), like ee/app/services/ee/mcp/tools/work_items/save_work_item_service.rb.
  • Create-only is an intentional exception to the save_ convention. Update (PUT /projects/:id) is a follow-up.

4. Write specs

Create spec/services/mcp/tools/projects/save_project_service_spec.rb. Mirror the structure of spec/services/mcp/tools/merge_requests/save_merge_request_service_spec.rb.

Cover at minimum:

  • Input schema includes all expected parameters
  • tool_name returns 'save_project'
  • namespace_arguments returns { group: :namespace_id }
  • Through execute (not by calling the protected select_tool or transform_arguments): creates a project with namespace_id as a numeric ID and as a full path (use let_it_be(:group) and a user with Owner role)
  • Authorization: a user without create access receives an error response, not an exception
  • EE spec under ee/spec/services/mcp/tools/projects/: the EE template params appear in the input schema; the CE spec asserts they don't
  • A tools/call case in spec/requests/api/mcp/handlers/call_tool_spec.rb

5. Register and verify

Call tools/list on POST /api/v4/mcp (or use MCP Inspector) to confirm save_project appears. Then call it with tools/call and confirm the project is created in the target namespace.

Add a save_project entry with a history block to doc/user/model_context_protocol/mcp_server_tools.md.

Notes for reviewers

  • Template params (use_custom_template, group_with_project_templates_id) are EE-only at the API level, so they live in EE code. On CE, declared_params drops them silently and the project is created without the template, so CE must not advertise them.
  • The AppSec review for this tool was opened at gitlab-com/gl-security/product-security/appsec/appsec-reviews#320. Implementation can proceed in parallel; the review must be resolved before merge.
  • Do not expose import_url, cicd_catalog_enabled, repository_storage, or any admin-only params.

Feature Usage Metrics

Does this feature require an audit event?

Covered by existing project creation audit events.

Edited by 🤖 GitLab Bot 🤖