GitLab
Connect GitLab to read and edit code, review and merge merge requests, manage issues and epics, and run and debug CI/CD pipelines.
You paste a GitLab personal access token with the api scope (it starts with glpat- on gitlab.com), plus your GitLab's address only if you run GitLab Self-Managed or Dedicated.
- Setup time
- 3 min
- Auth
- API credentials
- API base URL
- https://gitlab.com/api/v4
- Rate limits
- GitLab.com currently allows 2,000 authenticated API requests a minute per user, with tighter limits on some list endpoints (GET /projects 2,000 per 10 minutes, GET /groups 50 a minute). Throttled requests get 429 with a Retry-After header. On Self-Managed, your administrator sets the limits.
Before you begin
- A GitLab account on gitlab.com, or on your own GitLab Self-Managed or Dedicated instance
- Membership of the groups and projects the MCP should reach, with the role the work needs (for example Developer to push or run pipelines, Maintainer to merge into a protected branch)
- Personal access tokens allowed for your account. An administrator can switch them off, and a group or instance can require fine-grained tokens instead of legacy ones
- For Self-Managed: an https address that is reachable from the internet, because PopMCP's servers call it
Get your credentials
Open GitLab's token page from the PopMCP form
Sign in to gitlab.com, then click the link under Personal access token on the PopMCP connect form. It opens a legacy personal access token form with the name PopMCP, a description and the api scope already filled in. To get there by hand: select your avatar, Edit profile, then Access > Personal access tokens, and choose Legacy token from the Generate token dropdown.
Personal access tokens
You can generate a personal access token for each application you use that needs access to the GitLab API.
The link fills in the name, description and api scope. You only pick the expiry date.
Pick an expiry date and check the scope
Set Expiration date. GitLab caps it at 365 days from today unless your administrator changed the limit, and the connection stops working on that date. Under the scopes, keep api ticked so every tool can work. For an AI that should only read, untick api and tick read_api instead.
Personal access tokens
You can generate a personal access token for each application you use that needs access to the GitLab API.
read_user, read_repository and write_repository on their own are not enough: PopMCP needs api or read_api to reach the API. Older GitLab versions label the button Create personal access token.
Generate the token and copy it
Click Generate token. GitLab shows the new token once, at the top of the page. Copy it with the copy button; on gitlab.com it starts with glpat-.
Personal access tokens
You can generate a personal access token for each application you use that needs access to the GitLab API.
| Token name | Scopes | Created | Expires |
|---|---|---|---|
| PopMCPLegacy token | api | Oct 19, 2026 | in 1 year |
Lost it before copying? Revoke the token in this table and generate a new one.
Or create a fine-grained token for chosen groups and projects
GitLab 18.10 and later also offer fine-grained tokens (generally available since 19.2). From the Generate token dropdown choose Fine-grained token, fill in Name, Description and Expiration date, pick the groups and projects under Group and project access, then under Add resource permissions select each resource the AI should use and its permission. Click Generate token and copy it. Tools outside what you grant are refused by GitLab, and GitLab is still extending fine-grained support for GraphQL, so the work item and GraphQL tools may not work with one.
Personal access tokens
You can generate a personal access token for each application you use that needs access to the GitLab API.
Every request needs both a matching token permission and a role in GitLab that allows the action.
On GitLab Self-Managed or Dedicated, create the token on your own GitLab
The form's link always opens gitlab.com. For your own instance, open your GitLab's address followed by /-/user_settings/personal_access_tokens and create the token there the same way. A token made on gitlab.com is not accepted by another GitLab, and the reverse.
Open https://gitlab.example.com/-/user_settings/personal_access_tokens?name=PopMCP&scopes=api (replace gitlab.example.com with your GitLab domain).
Paste the token into PopMCP
In PopMCP, paste the token into Personal access token. For Self-Managed or Dedicated, also enter your instance in GitLab address (self-managed only), for example https://gitlab.example.com; leave it empty for gitlab.com. Connect, and PopMCP checks the token against that GitLab straight away.
Connect in PopMCP
Open your workspace, choose GitLab in the marketplace, and fill in the connect dialog:
| Field | What to enter |
|---|---|
| Personal access tokensecret | Open the link below: GitLab's token page opens with the name and the api scope filled in. Pick an expiry date (GitLab allows up to a year), press Generate token, copy it and paste it here. On GitLab Self-Managed or Dedicated, create it on your own GitLab instead: its token page is your GitLab's address followed by /-/user_settings/personal_access_tokens. Project and group access tokens work too. Stored encrypted.Encrypted with AES-256-GCM on save and never shown again. |
| GitLab address (self-managed only)text | Leave empty for gitlab.com. For GitLab Self-Managed or Dedicated, enter its address and paste a personal access token created there: its token page is that address followed by /-/user_settings/personal_access_tokens (the link above opens gitlab.com's). |
PopMCP verifies the credential against GitLab immediately. On success the connection flips to Verified and its MCP tools are provisioned.
Verify it worked
PopMCP marks the GitLab connection Verified as your username, such as @dana.reyes (followed by on gitlab.example.com for your own instance), and notes the date the token expires. Asking the AI to list your projects or your open merge requests returns real results from that GitLab.
Troubleshooting
"GitLab (gitlab.com) did not accept this token. It may have expired or been revoked, or it was created on a different GitLab."
Why: The token expired, was revoked, was copied incompletely, or was created on gitlab.com while the connection points at your own instance (or the other way round).
Fix: Create a new token on the same GitLab the connection points at, and enter that GitLab's address in **GitLab address (self-managed only)** if it is not gitlab.com.
"This token cannot read the API. Create a token with the api scope (or read_api for read-only use)"
Why: The token was created with only read_user, read_repository or another scope that does not include the API.
Fix: Create a new token from the form's link, which ticks api, or tick read_api for read-only use.
"That is a deploy token, which only works for git and the registries."
Why: A deploy, runner, pipeline trigger, feed or CI/CD job token was pasted. None of them can use the API.
Fix: Paste a personal access token (or a project or group access token) from **Edit profile**, **Access**, **Personal access tokens**.
"No GitLab answered at gitlab.example.com. Check the address"
Why: The address is mistyped, the instance only serves plain http, or it sits behind a firewall or VPN that PopMCP's servers cannot get through.
Fix: Enter the https address you open GitLab at, such as `https://gitlab.example.com`, and make sure it is reachable from the internet.
Reads work but writes fail with insufficient_scope
Why: The token has read_api, not api.
Fix: Create a token with the api scope and reconnect. PopMCP's own read-only setting still decides whether write tools run.
A merge, push or pipeline run fails with 403
Why: Your GitLab role in that project does not allow the action, for example Developer to push or run pipelines, or Maintainer to merge into a protected branch.
Fix: Ask a project Maintainer or Owner for the role the work needs. The token can never do more than your account.
You cannot create a legacy token
Why: Your instance or top-level group requires fine-grained personal access tokens (the Require fine-grained personal access tokens after a specific date setting), or an administrator disabled personal access tokens.
Fix: Create a fine-grained token with permissions on the groups and projects you need, or ask your administrator which kind of token is allowed.