# Usage Examples This document provides practical usage examples for gitlab-mcp-server, demonstrating common workflows with MCP tools, resources, and prompts. > **DiΓ‘taxis type**: How-to > **Audience**: πŸ‘€ End users, AI assistant users > **Prerequisites**: gitlab-mcp-server configured and running --- ## Setup ### Stdio Mode (Default) Configure your MCP client (VS Code, Cursor, Copilot CLI, OpenCode) with: ```json { "mcpServers": { "gitlab-mcp-server": { "command": "/path/to/gitlab-mcp-server", "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxx" } } } } ``` For self-managed GitLab, add `GITLAB_URL=https://gitlab.example.com`. ### HTTP Mode Start the server with HTTP transport for multi-client scenarios: ```bash ./gitlab-mcp-server --http \ --gitlab-url=https://gitlab.com \ --http-addr=:8080 \ --max-http-clients=100 ``` Replace `https://gitlab.com` with your self-managed GitLab URL when needed. Clients connect to `http://localhost:8080/mcp` with their GitLab token in the `Authorization` header. ## Conversational Examples You do not need to know tool names or parameters. Just ask naturally: ### "What merge requests need my review?" The AI calls the `my_pending_reviews` prompt and returns a list of MRs assigned to you as reviewer, with clickable links to each one in GitLab. ### "Create an issue about fixing the login timeout" The AI calls `gitlab_create_issue` with a title derived from your request. It may ask you for the project name and any labels before creating the issue. ### "Generate release notes from v1.1 to v1.2" The AI calls the `generate_release_notes` prompt which collects commits and MRs between the two tags and produces formatted release notes grouped by type (features, fixes, breaking changes). --- ## Common Workflows ### 1. Project Discovery Use meta-tools for guided tool discovery: ```text User: "What tools are available for merge requests?" β†’ Call gitlab_merge_request with action "help" β†’ Returns: list of all MR-related tools with descriptions ``` Individual tool approach: ```text User: "List my projects" β†’ Call gitlab_list_projects with owned=true β†’ Returns: paginated list of projects with IDs and paths ``` ### 2. Merge Request Lifecycle #### Create a Branch and MR ```text 1. gitlab_create_branch(project_id="42", branch="feature/new-login", ref="main") 2. gitlab_create_or_update_file(project_id="42", branch="feature/new-login", ...) 3. gitlab_create_merge_request(project_id="42", source_branch="feature/new-login", target_branch="main", title="Add new login page") ``` #### Review a Merge Request ```text 1. gitlab_get_merge_request(project_id="42", merge_request_iid=15) 2. gitlab_list_mr_changes(project_id="42", merge_request_iid=15) 3. Prompt: review_mr(project_id="42", merge_request_iid="15") β†’ Returns structured code review with risk categorization ``` #### Approve and Merge ```text 1. gitlab_approve_merge_request(project_id="42", merge_request_iid=15) 2. gitlab_accept_merge_request(project_id="42", merge_request_iid=15, squash=true) ``` ### 3. Issue Management ```text 1. gitlab_create_issue(project_id="42", title="Fix login bug", labels=["bug", "P1"]) 2. gitlab_update_issue(project_id="42", issue_iid=10, assignee_ids=[5]) 3. gitlab_create_issue_note(project_id="42", issue_iid=10, body="Investigating...") 4. gitlab_close_issue(project_id="42", issue_iid=10) ``` ### 4. CI/CD Pipeline Monitoring ```text 1. Resource: gitlab://project/42/pipelines/latest β†’ Returns latest pipeline status 2. gitlab_list_pipeline_jobs(project_id="42", pipeline_id=100) 3. gitlab_get_job_log(project_id="42", job_id=500) β†’ Returns job console output for debugging ``` ### 5. Release Management ```text 1. gitlab_create_tag(project_id="42", tag_name="v1.2.0", ref="main", message="Release 1.2.0") 2. gitlab_create_release(project_id="42", tag_name="v1.2.0", name="Version 1.2.0", description="...") 3. Prompt: generate_release_notes(project_id="42", from="v1.1.0", to="v1.2.0") β†’ Returns structured release notes from commits between tags ``` ### 6. Team Dashboards #### Personal Dashboard ```text Prompt: my_open_mrs() β†’ All your open MRs across projects Prompt: my_pending_reviews() β†’ MRs waiting for your review Prompt: my_issues() β†’ All issues assigned to you Prompt: daily_standup(project_id="42") β†’ Your standup summary ``` #### Manager Dashboard ```text Prompt: team_overview(group_id="7") β†’ Team member workloads Prompt: reviewer_workload(group_id="7") β†’ Review distribution analysis Prompt: group_mr_dashboard(group_id="7") β†’ All group MRs with filters Prompt: user_activity_report(group_id="7", username="johndoe") β†’ Individual report ``` ### 7. Project Health Monitoring ```text Prompt: project_health_check(project_id="42") β†’ Returns: pipeline status, open MR summary, branch hygiene, recommendations Prompt: stale_items_report(project_id="42", stale_days="30") β†’ Returns: MRs and issues not updated in 30+ days Prompt: milestone_progress(project_id="42") β†’ Returns: completion percentages for all active milestones ``` ## Using Resources Resources provide read-only data via URI patterns: ```text gitlab://user/current β†’ Your profile gitlab://groups β†’ All accessible groups gitlab://project/42 β†’ Project metadata gitlab://project/42/members β†’ Project members gitlab://project/42/labels β†’ Project labels gitlab://project/42/milestones β†’ Project milestones gitlab://project/42/branches β†’ Project branches gitlab://project/42/issues β†’ Open issues gitlab://project/42/releases β†’ Project releases gitlab://project/42/tags β†’ Repository tags gitlab://project/42/pipelines/latest β†’ Latest pipeline gitlab://project/42/pipeline/100 β†’ Specific pipeline gitlab://project/42/pipeline/100/jobs β†’ Pipeline jobs gitlab://project/42/mr/15 β†’ Specific MR gitlab://project/42/issue/10 β†’ Specific issue gitlab://group/7 β†’ Group details gitlab://group/7/members β†’ Group members gitlab://group/7/projects β†’ Group projects ``` ## Dynamic Discovery and Execution Dynamic mode is the default tool surface. The model first searches the canonical action catalog, then executes one validated action with exact parameters: ```text Call: gitlab_find_action(query="list open merge requests") β†’ Returns: merge_request.list with input schema, examples, safety metadata, and output summary Call: gitlab_execute_action(action="merge_request.list", params={project_id:"42", state:"opened"}) β†’ Executes the GitLab API request and returns Markdown plus structured content ``` Use this flow when startup context or visible tool count matters. It reaches the same catalog as meta-tools and individual tools while exposing only `gitlab_find_action` and `gitlab_execute_action` in `tools/list`. ## Meta-Tool Discovery With `TOOL_SURFACE=meta`, 32 domain-level meta-tools (48 on self-managed Enterprise/Premium, 49 on GitLab.com Enterprise/Premium with Orbit) provide domain dispatcher tools: ```text Call: gitlab_project(action="help") β†’ Returns: all project-related tools with descriptions and parameters Call: gitlab_merge_request(action="list", project_id="42") β†’ Dispatches to gitlab_list_merge_requests with the given parameters ``` Available meta-tool domains: `project`, `branch`, `tag`, `release`, `merge_request`, `mr_review`, `repository`, `group`, `issue`, `pipeline`, `job`, `user`, `wiki`, `environment`, `ci_variable`, `template`, `admin`, `access`, `package`, `snippet`, `feature_flags`, `search`, `runner`, `analyze`. ## Error Handling All tools return actionable error messages that guide toward solutions: ```json { "isError": true, "content": [{ "type": "text", "text": "Project not found: '999'. Verify the project ID exists and your token has access. Use gitlab_list_projects to find valid project IDs." }] } ```