Multi-GitLab Instance Setup Guide

Configure GitLab MCP to work with multiple GitLab instances using context management and profiles.

Overview

Many organizations use multiple GitLab instances — a self-hosted instance for internal projects and GitLab.com for open-source work. GitLab MCP supports switching between instances using the context management system.

Tools used: manage_context

Understanding Context

The context system manages your current session configuration:

• Host — Which GitLab instance you're connected to
• Preset — Predefined configuration profiles
• Scope — Restrict operations to a specific namespace
• Mode — Authentication mode (PAT or OAuth)

View Current Context

"Show me my current GitLab context"

// manage_context
{
  "action": "show"
}

This returns your active host, preset, scope, and authentication mode.

Setting Up Presets

Presets are predefined configurations you can switch between. They're configured via environment variables at startup.

Example Configuration

# .env file for multiple instances

# Instance 1: Company GitLab (default)
GITLAB_API_URL=https://gitlab.company.com
GITLAB_TOKEN=glpat-company-token

# Instance 2: GitLab.com (via preset)
# Presets are defined in the server configuration

List Available Presets

"What presets are available?"

// manage_context
{
  "action": "list_presets"
}

Switch Between Presets

"Switch to the open-source preset for GitLab.com work"

// manage_context
{
  "action": "switch_preset",
  "preset": "open-source"
}

Scoping to a Namespace

Restrict all operations to a specific group or project. This is useful when working within a team boundary.

Scope to a Group

"Focus all operations on the backend group"

// manage_context
{
  "action": "set_scope",
  "namespace": "backend",
  "includeSubgroups": true
}

All subsequent browse_* and manage_* operations will be limited to this namespace.

Scope to a Project

"Scope to my-org/api only"

// manage_context
{
  "action": "set_scope",
  "namespace": "my-org/api"
}

Reset Context

"Restore the initial context (host, preset, scope)"

// manage_context
{
  "action": "reset"
}

Accounts in OAuth Mode

With OAuth, a connection works as the GitLab user who signed in, on that user's instance: calls and the tool list stay there. To work as another user or on another instance, sign in to it; to narrow what a chat may do, switch its preset or scope as shown above.

Workflow: Switching Between Instances

Morning: Internal Work

1. Context shows company GitLab (default)
2. "Show me my open MRs in the backend group"
3. "Review MR !42 in internal/api"
4. Work on internal projects...

Afternoon: Open Source

1. "Switch to the open-source preset"
2. "List my todos on GitLab.com"
3. "Check pipeline status for my-oss/library"
4. Work on public projects...

Back to Internal

1. "Switch back to the default preset"
2. "Continue reviewing internal MRs"

Configuration Tips

Environment Variables

Variable	Purpose
GITLAB_API_URL	API endpoint for the instance
GITLAB_TOKEN	Personal access token
GITLAB_PROJECT_ID	Default project scope
GITLAB_ALLOWED_PROJECT_IDS	Restrict to specific projects

Security Considerations

• Use different tokens for each instance
• Apply minimum required scopes per token
• Use read-only mode for production instances
• Consider OAuth for multi-user environments

Self-Hosted Setup

For self-hosted GitLab instances:

# Corporate instance
GITLAB_API_URL=https://gitlab.internal.company.com
GITLAB_TOKEN=glpat-internal-token

# Additional settings for self-hosted
# TLS verification, custom CA, etc.

See the TLS/HTTPS guide for self-hosted certificate configuration.

Troubleshooting

"Not authorized" errors after switching

• Verify the token for the target instance is valid
• Check token scopes match required operations
• Ensure the API URL is correct (base URL without /api/v4 suffix)

Scope not applying

• Verify the namespace path is correct
• Check if the namespace is a group vs project
• Use show action to confirm current context

Can't switch presets

• Verify presets are configured in the server
• Use list_presets to see available options
• Check server startup logs for preset loading errors