Skip to content

Custom Agents and Multiple PAT Setup

This guide explains how to run gitlab-mcp for custom agents, single-user PAT setups, multi-user deployments, and restricted tool surfaces.

Local Single-PAT Setup

Use this when one local MCP client should access GitLab with one Personal Access Token.

GITLAB_PERSONAL_ACCESS_TOKEN=glpat-... \
GITLAB_API_URL=https://gitlab.com/api/v4 \
npx -y @zereight/mcp-gitlab

In this mode:

  • The server process uses GITLAB_PERSONAL_ACCESS_TOKEN.
  • The token is shared by every request handled by that local process.
  • This is the simplest setup for stdio clients and local development.

Multi-User or Multiple-PAT Setup

Use remote authorization when different users or agent sessions need different GitLab tokens.

STREAMABLE_HTTP=true \
REMOTE_AUTHORIZATION=true \
GITLAB_API_URL=https://gitlab.com/api/v4 \
npx -y @zereight/mcp-gitlab

Clients send their GitLab token on each HTTP session:

Authorization: Bearer glpat-user-token

or:

Private-Token: glpat-user-token

In this mode:

  • Each session stores its own token.
  • Tokens from one session are not reused for another session.
  • SESSION_TIMEOUT_SECONDS controls inactivity expiration.
  • After a session expires, the client must send auth headers again.

Do not put user PATs into a shared server config. The shared server should only enable remote authorization and let each client provide its own token.

Multiple GitLab Instances

Enable dynamic API URL support when one server must connect to different GitLab instances.

STREAMABLE_HTTP=true \
REMOTE_AUTHORIZATION=true \
ENABLE_DYNAMIC_API_URL=true \
npx -y @zereight/mcp-gitlab

Clients include the target instance:

X-GitLab-API-URL: https://gitlab.example.com/api/v4

/api/v4 URLs are recommended. The server also accepts a GitLab base URL and normalizes it by appending /api/v4.

Tool Customization

Custom agents can expose only the tools they need.

GITLAB_TOOLSETS=issues,merge_requests,projects \
GITLAB_TOOLS=get_file_contents \
GITLAB_DENIED_TOOLS_REGEX="^(delete_|merge_)" \
npx -y @zereight/mcp-gitlab

Available controls:

  • GITLAB_TOOLSETS: expose named tool groups, such as issues, merge_requests, projects, or pipelines.
  • GITLAB_TOOLS: add individual tool names on top of enabled toolsets.
  • GITLAB_DENIED_TOOLS_REGEX: hide tools whose names match a regular expression.
  • GITLAB_TOOL_POLICY_APPROVE: expose tools but require _confirmed: true before execution.
  • GITLAB_TOOL_POLICY_HIDDEN: hide specific tools from tools/list.

Example Configurations

Local Single PAT

GITLAB_PERSONAL_ACCESS_TOKEN=glpat-local-user \
GITLAB_API_URL=https://gitlab.com/api/v4 \
npx -y @zereight/mcp-gitlab

Hosted Multi-User HTTP Server

STREAMABLE_HTTP=true \
REMOTE_AUTHORIZATION=true \
SESSION_TIMEOUT_SECONDS=3600 \
GITLAB_API_URL=https://gitlab.com/api/v4 \
npx -y @zereight/mcp-gitlab

Each client sends Authorization: Bearer <PAT> or Private-Token: <PAT>.

Restricted Agent

STREAMABLE_HTTP=true \
REMOTE_AUTHORIZATION=true \
GITLAB_TOOLSETS=issues,merge_requests,projects \
GITLAB_DENIED_TOOLS_REGEX="^(delete_|merge_)" \
GITLAB_TOOL_POLICY_APPROVE="create_issue,update_issue,create_merge_request" \
npx -y @zereight/mcp-gitlab

This exposes issue, merge request, and project tools while hiding destructive delete and merge operations. Selected write tools remain visible but require explicit confirmation.

Security Notes

  • Use HTTPS for remote deployments.
  • Do not hard-code user PATs into shared agent configs.
  • Prefer read-only PAT scopes for read-only agents.
  • Isolate deployment secrets from per-user GitLab tokens.
  • Keep SESSION_TIMEOUT_SECONDS short enough for your deployment risk profile.