# GitLab setup for PopMCP 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. - Auth: API credentials - Setup time: 3 min - API base URL: https://gitlab.com/api/v4 - Credentials screen: https://gitlab.com/-/user_settings/personal_access_tokens - Provider docs: https://gitlab.com/-/user_settings/personal_access_tokens?name=PopMCP&description=Lets+your+AI+assistant+work+with+GitLab+through+PopMCP&scopes=api ## 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 ### 1. 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. Screen: https://gitlab.com/-/user_settings/personal_access_tokens?name=PopMCP&description=Lets+your+AI+assistant+work+with+GitLab+through+PopMCP&scopes=api ### 2. 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. Screen: https://gitlab.com/-/user_settings/personal_access_tokens?name=PopMCP&description=Lets+your+AI+assistant+work+with+GitLab+through+PopMCP&scopes=api ### 3. 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-`. Screen: https://gitlab.com/-/user_settings/personal_access_tokens ### 4. 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. Screen: https://gitlab.com/-/user_settings/personal_access_tokens ### 5. 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. Screen: https://gitlab.example.com/-/user_settings/personal_access_tokens?name=PopMCP&scopes=api (replace gitlab.example.com with your GitLab domain) ### 6. 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. ## Fields PopMCP asks for - Personal access token (personalAccessToken) [required]: 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. - GitLab address (self-managed only) (gitlabUrl): 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). ## Verify 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." Cause: 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)" Cause: 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." Cause: 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" Cause: 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 Cause: 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 Cause: 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 Cause: 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. --- Source: https://www.docs.popmcp.com/docs/integrations/gitlab/