Project discovery

Most actions take a project_id, and a model working in a checkout often holds only the git remote. discover_project.resolve turns a complete remote URL, as git remote -v prints it or .git/config holds it, in HTTPS or SSH form, into the project and its ID, and only reads. When the project path or ID is already known it is not needed: pass that to the action directly.

Sample questions

• “Which GitLab project is this repository?”
• “Find the project ID for git@gitlab.example.com:group/app.git”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as discover_project.resolve, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
• Meta and individual (GITLAB_MCP_TOOL_SURFACE=meta or individual): each action is a tool of its own, such as gitlab_discover_project, under the same name on both surfaces, with its parameters as the arguments.

Availability

Every tier serves the whole group, on self-managed instances and on GitLab.com alike.

Read-only actions: 1 of 1, the ones a deployment in read-only mode keeps.

Actions

The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served.

Action	Individual
discover_project.resolve	gitlab_discover_project

discover_project.resolve

Resolve a full git remote URL to a GitLab project and return its project_id and metadata. Read-only. Performs a lookup against the GitLab Projects API. No side effects.

When to use: only when the user or workspace provides a complete git remote URL from .git/config ([remote “origin”] url = …) or from ‘git remote -v’. If the prompt already provides a project path such as group/project or a numeric project ID, pass that value directly as params.project_id to the requested GitLab tool instead of calling discovery. Do not synthesize, guess, or add .git to a project path to create a remote URL. NOT for: searching projects by name (use search.projects), listing a user’s projects (use project.list_user_projects), verifying GitLab connectivity or authentication (use server.status), or pre-checking workflows where project_id is already known.

IMPORTANT: pass the complete URL exactly as it appears. Do NOT strip the git@ prefix from SSH URLs. Supported formats (a URL scheme or git@ user prefix is required):

• HTTPS: https://gitlab.example.com/group/project.git
• SSH shorthand: git@gitlab.example.com:group/project.git
• SSH protocol: ssh://git@gitlab.example.com/group/project.git

Returns: {id, name, path, path_with_namespace, web_url, description, default_branch, visibility, http_url_to_repo, ssh_url_to_repo, extracted_path}. Errors: 404 not found (hint: project may be private, so verify token permissions), 403 forbidden (hint: token lacks read_api scope).

See also: project.get, server.status, search.projects.

• Meta-tool: gitlab_discover_project, a tool of its own
• Individual tool: gitlab_discover_project
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
remote_url	string	yes	Full git remote URL (HTTPS or SSH) exactly as shown in .git/config or ‘git remote -v’ output. IMPORTANT: pass the complete URL including the scheme (https://) or user prefix (git@). Examples: ‘https://gitlab.example.com/group/project.git’ or ‘git@gitlab.example.com:group/project.git’. Do not pass plain project paths such as group/project, and do not synthesize URLs by adding .git to a project path. Project paths are already valid project_id values.