Agent Setup Instructions

Follow these steps to configure the GitLab MCP server. Complete each step in order.

1. Step 1 — Verify GitLab Token

   A GitLab Personal Access Token (PAT) is required. If the token is YOUR_PAT_HERE or empty, ask the user for their GitLab PAT before proceeding. The token must have the api scope for full functionality (write tools, git operations). If the token has only read_api, write tools will be disabled. For git operations (clone, push), the user needs Maintainer+ role on the project so the server can create short-lived project-scoped tokens. If they have only Developer role, the server will fall back to using their PAT directly.

   Once obtained, use it in place of YOUR_PAT_HERE in all subsequent steps.

2. Step 2 — Configure MCP Server

   Add the MCP server to the user's AI assistant. Choose the platform below and apply the configuration. Replace YOUR_PAT_HERE with the actual token.

   Open WebUI

   1. Open Open WebUI → ⚙️ Settings → Integrations
   2. Under Manage tool servers, click + Add a tool server
   3. Select OpenAPI as the server type
   4. Enter a Name (e.g., gitlab)
   5. Enter the URL: https://gitlab-mcp.pyja.in/openapi
   6. Set Auth to Bearer
   7. Paste the user's GitLab PAT into the token field
   8. Click Save

   Screenshot reference: open-webui-integrations.png — shows the exact location of the "Add a tool server" button.

   Opencode

   Add to ~/.config/opencode/opencode.json:

   {
     "mcp": {
       "gitlab": {
         "type": "remote",
         "url": "https://gitlab-mcp.pyja.in/mcp",
         "enabled": true,
         "oauth": false,
         "headers": {
           "Authorization": "Bearer YOUR_PAT_HERE"
         }
       }
     }
   }

   Verify with opencode mcp list.

   Claude Code

   Recommended — add to .mcp.json (project) or ~/.claude.json (user):

   {
     "mcpServers": {
       "gitlab": {
         "type": "http",
         "url": "https://gitlab-mcp.pyja.in/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_PAT_HERE"
         }
       }
     }
   }

   Alternative — use the CLI:

   claude mcp add --transport http gitlab https://gitlab-mcp.pyja.in/mcp \
     --header "Authorization: Bearer YOUR_PAT_HERE"

   Note

   The CLI --header flag has known issues in some Claude Code versions and may not persist the auth header. If the CLI method doesn't work, use the .mcp.json approach above.

   Cursor

   Add to Cursor settings (Cmd/Ctrl + , → MCP):

   {
     "mcpServers": {
       "gitlab": {
         "type": "streamable-http",
         "url": "https://gitlab-mcp.pyja.in/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_PAT_HERE"
         }
       }
     }
   }

   Cline

   Add to Cline MCP settings. The type field is required — without it, Cline defaults to SSE transport which will fail with a 405 error.

   {
     "mcpServers": {
       "gitlab": {
         "type": "streamableHttp",
         "url": "https://gitlab-mcp.pyja.in/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_PAT_HERE"
         }
       }
     }
   }

3. Step 3 — Offer Available Skills

   The following skills are available from https://gitlab-mcp.pyja.in/skills.git. Present them to the user and offer to install:

   • gitlab-researcher — Research open issues using parallel subagents, then post detailed findings as issue comments. Defaults to researching all open issues.
   • gitlab-solver — Implement fixes for issues with full verification, testing, and MR creation. Keeps the user in the loop with plan-then-execute.
   • gitlab-reviewer — Review merge requests with deep research into alternative solutions, best practices, and architectural improvements. Defaults to reviewing all open MRs.

   These three skills work together as a pipeline: gitlab-researcher investigates issues, gitlab-solver implements fixes, and gitlab-reviewer reviews the resulting merge requests.

   Migrating from Old Skills

   If the user already has issue-researcher or code-reviewer installed, they should be uninstalled first before installing the new skills:

   # Uninstall old skills (global)
   npx skills remove issue-researcher -g
   npx skills remove code-reviewer -g
   
   # Uninstall old skills (project-local)
   npx skills remove issue-researcher
   npx skills remove code-reviewer

   If the user agrees to install skills, proceed to Step 4. If not, skip to Step 6.

4. Step 4 — Choose Skills Installation Scope

   Ask the user whether to install skills globally (available to all projects) or project-local (only for the current project). This decision is independent of the MCP server configuration above.

   • Global: Skills apply to all projects. Use the -g flag with npx skills add.
   • Project-local: Skills only apply to the current project. Omit -g. Detect the current working directory and run from the project root.

5. Step 5 — Install Skills

   Run npx skills add with the skills repository URL and flags based on the scope chosen in Step 4:

   Global installation:

   npx skills add https://gitlab-mcp.pyja.in/skills.git --all -g

   Project-local installation (run from the project root):

   npx skills add https://gitlab-mcp.pyja.in/skills.git --all

   Specific skill only:

   npx skills add https://gitlab-mcp.pyja.in/skills.git --skill gitlab-researcher -g

   For a specific agent (e.g., opencode, claude-code, cursor):

   npx skills add https://gitlab-mcp.pyja.in/skills.git --all -g -a opencode

   List available skills before installing:

   npx skills add https://gitlab-mcp.pyja.in/skills.git --list

6. Step 6 — Restart

   Inform the user to restart their AI harness so the new MCP server and skills are loaded. Skills are loaded on-demand by the agent after restart.