Use this file to discover all available pages before exploring further.
The GitLab app provides read/write access to the GitLab DevOps platform via its REST v4 API. It can be used either as a Builder app (automations call GitLab instructions directly) or as a remote MCP server consumed by an Knowledges agent — covering projects, issues, merge requests, pipelines, branches, commits, releases, CI/CD variables, deploy keys, webhooks, wikis, groups and users. Supports both static Personal Access Tokens and OAuth2 authorization-code per-user delegation.
Project Management
Projects, issues, merge requests, labels, milestones and wikis
CI/CD & DevOps
Pipelines, jobs, environments, CI variables, deploy keys and webhooks
Flexible Auth
Static PAT shared across the tenant, or OAuth2 per-user delegation (each user signs in with their own GitLab account)
Either a Personal Access Token with api scope (Preferences > Access Tokens), or an OAuth application registered at User Settings > Applications (https://gitlab.com/-/user_settings/applications) with api scope
Base URL (default: https://gitlab.com/api/v4 — override for self-hosted instances)
Base URL of the GitLab API (default https://gitlab.com/api/v4). Override for self-hosted instances.
Personal Access Token
GitLab PAT with api scope, stored as a workspace secret. Optional if OAuth2 is configured. Passed as Authorization: Bearer <token>.
OAuth2 Client ID
GitLab OAuth Application Client ID. Create an OAuth application at https://gitlab.com/-/user_settings/applications.
OAuth2 Client Secret
OAuth Application Client Secret (shown once on creation), stored as a workspace secret.
OAuth Callback URL
Auto-populated on install — paste this value into the OAuth application’s Redirect URI at GitLab.
OAuth Scopes
Space-separated scopes (default: api).
MCP Endpoint
Auto-populated on install — URL of the MCP endpoint for this instance.
MCP API Key
Auto-populated on install — signed key used in the mcp-api-key header. Do not modify.
MCP Endpoint and MCP API Key are generated automatically by the onInstall flow and are only needed to expose this instance as an MCP server (see the next tab).
The GitLab app ships with a built-in MCP server. Each app instance gets its own signed mcp-api-key that encodes the workspace ID and a credentials lookup URL — the GitLab API key itself is never passed through headers and is resolved server-side from the app configuration.
Agents consume MCP servers directly through Agent Creator capabilities. This is the preferred way to expose GitLab to an agent.
1
Create or open a workspace
From the Prisme.ai console, create a new workspace (or open the one that will host the connector).
2
Install the GitLab app
Open the workspace Imports panel, search for GitLab and install it.
3
Configure the credentials
Open the freshly installed app instance settings and fill in the required fields (see the Usage as App tab for the field-by-field reference).
4
Copy the MCP endpoint and API key
Still on the app instance configuration page, copy the values of MCP Endpoint and MCP API Key — both are generated automatically on install.
5
Open Agent Creator
Switch to Agent Creator and open the agent you want to extend.
6
Add a capability
Add a new capability to the agent:
If a dedicated GitLab capability exists — select it and paste the MCP API Key into the mcp-api-key field. The server URL is already wired.
Otherwise — select the generic custom_mcp capability, paste the MCP Endpoint into the Server URL field, then open the Headers field and add an mcp-api-key entry whose value is the MCP API Key copied earlier:
{ "mcp-api-key": "your-mcp-api-key"}
7
Save
The agent now has access to every GitLab tool exposed by the MCP server.
8
Brief the agent in its system prompt
Wiring the capability is not enough — the agent also needs to know the MCP exists and when to reach for it. Add a short paragraph to the agent’s system prompt. Copy-pasteable starter:
You have access to the GitLab MCP server. Use it whenever the user asks about GitLab content — projects, issues, merge requests, pipelines, jobs, branches, commits, tags, releases, milestones or members. Examples: "List my open merge requests", "What's failing in pipeline #1234?", "Create an issue in project X with label bug", "Show the latest release of my main project". Prefer calling MCP tools directly over guessing, and confirm with the user before any destructive action (close an issue, merge or revert an MR, delete a branch, cancel a pipeline).
Refine the trigger keywords (project names, group names, label conventions) so the agent reliably picks up the right intent in your context.
Use this flow to plug the GitLab MCP into an Knowledges agent that does not yet support the native MCP picker.
1
Install the GitLab app
Install and configure the app in the same workspace as your agent (see the Usage as App tab). Once configured, mcpEndpoint and mcpApiKey are auto-populated.
2
Copy the MCP credentials
Open the app instance config and copy the values of MCP Endpoint and MCP API Key.
3
Open your Knowledges project
Navigate to Advanced > Tools.
4
Add an MCP tool
Click Add and select the MCP tab.
5
Fill in the endpoint
Paste the MCP Endpoint URL copied from the app instance.
6
Add the auth header
In the Headers field, add the signed API key:
{ "mcp-api-key": "your-mcp-api-key"}
7
Save
The agent can now list and call GitLab tools through the MCP endpoint.
The signed mcp-api-key encodes the workspace ID and the getConfig webhook URL. The MCP server validates the signature using the central app secret and transparently fetches the GitLab API key and base URL from the installed app. Credentials are cached per tenant for 10 minutes.
List accessible projects. By default returns ALL accessible projects including public ones. Pass membership: true or owned: true to limit to the user’s own projects.
“Not configured” — The app instance has no API key. Generate one at the provider and paste it in the app configuration.“Invalid API key” (MCP) — The mcp-api-key header does not match the central app secret. Reinstall the app instance to regenerate a signed key.“Credentials lookup failed” — The MCP endpoint could not reach the getConfig webhook of the installed app. Verify that the app instance is still installed in the expected workspace.“Can’t approve own MR” — A GitLab project access token’s bot user counts as the MR author and cannot approve its own merge requests. Use a different token (PAT for a human user) for the approval step.“pipeline creation 404” — The target ref has no .gitlab-ci.yml at its root. Either commit a CI config first or pick a ref that has one.OAuth per-user delegation — Each GitLab user must click the connect tool once (from the AI agent) to authorize; the agent stores a per-user refresh token. Use disconnect to revoke.