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:
- Creates work items on the group level (epics) to track tasks.
- Concludes it needs to create a GitLab project first — only then can it create branches, commits, and MRs.
- Fails because no tool exists to create projects.
- 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:
- Permissions — only group owners/maintainers can create projects in a group namespace.
- 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 viaBase::AggregatedServiceapp/services/mcp/tools/projects/get_project_tool.rbandget_project_service.rb— the existing projects module structureapp/services/mcp/tools/base/api_service.rbandapi_tool.rb— the REST base classeslib/api/projects.rb— thePOST /projectsroute (around line 494) and theallow_mcp_access_createdeclaration at the topdoc/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→:coreannotations→{ readOnlyHint: false, destructiveHint: false }required→[](bothnameandpathare optional individually; the API enforcesat_least_one_of). Say "providename,path, or both" in the tool description.- In
select_tool, find the:create_projecttool fromtools - In
transform_arguments, resolve a full-pathnamespace_idto its numeric ID before forwarding.POST /projectsonly accepts an integer. - Override
self.namespace_argumentsto declare{ group: :namespace_id }so governance rules apply when a group namespace is targeted. Calls that target a personal namespace, or omitnamespace_id, resolve no group and are not governed. - Keep
input_schemato CE params and addprepend_mod. Add the two EE template params inee/app/services/ee/mcp/tools/projects/save_project_service.rbby overridinginput_schemawithsuper.deep_merge(properties: { ... }), likeee/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_namereturns'save_project'namespace_argumentsreturns{ group: :namespace_id }- Through
execute(not by calling the protectedselect_toolortransform_arguments): creates a project withnamespace_idas a numeric ID and as a full path (uselet_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/callcase inspec/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_paramsdrops 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.