Deployment¶
Deployment Options¶
gitlab-api supports local stdio, a loopback-only development listener, a
least-privilege stdio container, and a remote authenticated HTTPS boundary.
Provider endpoint, credential, selector, identity, and trust material are supplied
at runtime through AgentConfig; none is stored in this repository.
Installed stdio process¶
{
"mcpServers": {
"gitlab": {
"command": "gitlab-mcp",
"args": [],
"env": {"MCP_TOOL_MODE": "intent"}
}
}
}
Loopback development listener¶
Do not expose this listener beyond loopback. Network deployments require direct TLS
or an explicitly trusted TLS-terminating ingress, configured authentication, exact
MCP_ALLOWED_HOSTS, and an exact trusted-proxy CIDR policy.
Least-privilege local container¶
docker run -i --rm \
--read-only \
--cap-drop=ALL \
--security-opt=no-new-privileges \
--pids-limit=256 \
--tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
-e TRANSPORT=stdio \
registry.example.invalid/gitlab-api@sha256:<digest> gitlab-mcp
The operator projects the selected AgentConfig profile into the process at runtime; the image remains immutable and contains no environment connection profile.
Remote authenticated HTTPS endpoint¶
Store the real remote URL, outbound identity reference, and TLS-profile reference in
AgentConfig, not in MCP client JSON or documentation.
This page covers running gitlab-api as long-lived servers: the transports, a Docker
and giving it a DNS name with Technitium. To provision the GitLab instance it
connects to, see Backing Platform.
gitlab-apiships both an MCP server (console scriptgitlab-mcp) and an
Run the MCP server¶
The transport is selected with --transport (or the TRANSPORT env var):
Health check (HTTP transports):
Configuration (environment)¶
gitlab-api is configured entirely from the environment. The required set:
| Var | Default | Meaning |
|---|---|---|
GITLAB_URL |
https://gitlab.com |
GitLab instance base URL |
GITLAB_TOKEN |
(unset) | Personal / project / group access token |
GITLAB_TLS_PROFILE |
(unset) | Optional runtime TLS profile selector; verification is mandatory |
HOST |
0.0.0.0 |
Bind address (HTTP transports) |
PORT |
8000 |
Listen port (HTTP transports) |
TRANSPORT |
stdio |
stdio, streamable-http, or sse |
Each tool module is independently togglable with a *TOOL flag (for example
BRANCHESTOOL, PIPELINESTOOL, GRAPHQLTOOL) — every variable, with its default,
is documented in
.env.example.
Copy it to .env and fill in only what the operator use; the connector remains inactive when
GITLAB_TOKEN is absent.
Docker Compose¶
The repo ships docker/mcp.compose.yml.
It reads a sibling .env and publishes the HTTP server on :8000:
services:
gitlab-api-mcp:
image: example/gitlab-api@sha256:<digest>
container_name: gitlab-api-mcp
hostname: gitlab-api-mcp
restart: always
env_file:
- ../.env
environment:
- PYTHONUNBUFFERED=1
- HOST=0.0.0.0
- PORT=8000
- TRANSPORT=streamable-http
ports:
- "8000:8000"
healthcheck:
test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 30s
timeout: 10s
retries: 3
cp .env.example .env # then edit GITLAB_URL / GITLAB_TOKEN
docker compose -f docker/mcp.compose.yml up -d
docker compose -f docker/mcp.compose.yml logs -f
Behind a Caddy reverse proxy¶
Expose the HTTP server on a hostname with automatic TLS. Add to the operator's Caddyfile:
# Internal (self-signed) — homelab .example.invalid zone
gitlab-api.example.invalid {
tls internal
reverse_proxy gitlab-api-mcp:8000
}
Reload Caddy:
DNS with Technitium¶
Point the hostname at the host running Caddy. Via the Technitium API:
curl -s "http://technitium.example.invalid:5380/api/zones/records/add" \
--data-urlencode "token=$TECHNITIUM_DNS_TOKEN" \
--data-urlencode "domain=gitlab-api.example.invalid" \
--data-urlencode "zone=arpa" \
--data-urlencode "type=A" \
--data-urlencode "ipAddress=192.0.2.10" \
--data-urlencode "ttl=3600"
…or add an A record gitlab-api.example.invalid → <caddy-host-ip> in the Technitium web
console (http://technitium.example.invalid:5380). The ecosystem
technitium-dns-mcp automates
this as a tool.
Register with an MCP client¶
Add to the operator's client's mcp_config.json:
{
"mcpServers": {
"gitlab-api": {
"command": "uv",
"args": ["run", "gitlab-mcp"],
"env": {
"GITLAB_URL": "https://gitlab.example.com",
"GITLAB_TOKEN": "<your-gitlab-token>"
}
}
}
}
For a remote HTTP server, point the client at http://gitlab-api.example.invalid/mcp instead.