Configurer le MCP GitLab sur code-server

1. Objectif

Configurer et authentifier le serveur MCP GitLab dans OpenAI Codex, exécuté dans un conteneur Docker code-server hébergé sur Ubuntu Server, avec un navigateur Windows.

L'authentification utilise OAuth 2.0 et un tunnel SSH pour rendre accessible le callback OAuth de Codex sans exposer de ports supplémentaires sur Internet.

Architecture

Windows
│
├── Chrome / navigateur
│   └── http://127.0.0.1:23721
│
└── Tunnel SSH
    │
    │ Connexion au domaine SSH, port 3307
    │
    ▼
Box Internet
│
└── Redirection TCP 3307
    │
    ▼
Ubuntu Server
│
├── Serveur SSH
│
└── Docker : 127.0.0.1:23720
    │
    ▼
Conteneur code-server
│
├── socat : 0.0.0.0:23721
│   │
│   └── Redirection TCP
│       │
│       ▼
└── Codex OAuth : 127.0.0.1:23722

Tableau des ports

Port	Emplacement	Utilisation
`3307`	Box Internet	Port SSH public
`23720`	Ubuntu Server	Port Docker exposé uniquement en localhost
`23721`	Conteneur Docker	Port d'écoute de socat
`23721`	Windows	Port local du tunnel SSH
`23722`	Conteneur Docker	Listener OAuth de Codex

Sécurité : seul le port SSH 3307 doit être accessible depuis Internet. Les ports 23720, 23721 et 23722 ne doivent pas être exposés sur la box.

2. Configuration initiale (une seule fois)

2.1. Configurer Docker Compose

Dans le service code-server du fichier docker-compose.yml, vérifier la présence de :

services:
  code-server:
    ports:
      - "8218:8080"
      - "127.0.0.1:23720:23721"

Le port 23720 est accessible uniquement depuis la boucle locale du serveur Ubuntu.

Le port 23721 correspond au port interne sur lequel socat écoutera.

Vérifier également que le volume de configuration Codex est persistant :

volumes:
  - /home/darkmat/.docker/config/code-server/codex:/home/coder/.codex

Si la configuration Docker a été modifiée, appliquer les changements depuis le dossier contenant le fichier Compose :

docker compose up -d code-server

Docker Compose recrée le conteneur si sa configuration a changé.

2.2. Configurer Codex

Depuis le terminal intégré de code-server, ouvrir :

nano ~/.codex/config.toml

Ajouter les paramètres suivants au niveau racine du TOML, avant toute section [section] :

# MCP OAuth callback
mcp_oauth_callback_port = 23722
mcp_oauth_callback_url = "http://127.0.0.1:23721/callback"

Explications :

mcp_oauth_callback_port : port réel utilisé par Codex pour écouter le retour OAuth.
mcp_oauth_callback_url : adresse communiquée à GitLab pour rediriger le navigateur après authentification.

Codex peut ajouter automatiquement un identifiant à la fin du chemin /callback.

Vérifier également la déclaration du serveur MCP GitLab :

[mcp_servers.gitlab-http]
url = "https://gitlab.darkmat.fr/api/v4/mcp"

Si le MCP GitLab n'existe pas encore, il peut être créé avec :

codex mcp add gitlab-http \
  --url "https://gitlab.darkmat.fr/api/v4/mcp"

Important : utiliser le transport HTTP natif de Codex plutôt que mcp-remote.

3. Procédure d'authentification OAuth

À utiliser lors de la première connexion ou lorsqu'une nouvelle authentification interactive GitLab est nécessaire.

Étape 1 — Lancer socat dans code-server

Ouvrir un premier terminal dans code-server :

socat \
  TCP-LISTEN:23721,bind=0.0.0.0,reuseaddr,fork \
  TCP:127.0.0.1:23722

Cette commande :

Écoute sur le port 23721 du conteneur.
Accepte les connexions arrivant depuis le réseau Docker.
Redirige les connexions vers 127.0.0.1:23722, utilisé par Codex.
Permet de traiter plusieurs connexions grâce à fork.

Conserver ce terminal ouvert pendant toute l'authentification.

Étape 2 — Lancer le tunnel SSH depuis Windows

Ouvrir PowerShell sur Windows :

ssh -N -p 3307 -L 127.0.0.1:23721:127.0.0.1:23720 darkmat@darkmat.fr

Remplacer <DOMAINE_SSH> par le nom de domaine pointant vers la box Internet.

Paramètres :

Option	Signification
`-N`	N'exécute aucune commande distante
`-p 3307`	Utilise le port SSH public
`-L`	Crée une redirection de port local
`127.0.0.1:23721`	Port local utilisé sur Windows
`127.0.0.1:23720`	Destination sur Ubuntu Server

Conserver également cette fenêtre PowerShell ouverte.

Étape 3 — Vérifier le tunnel SSH

Dans un second PowerShell Windows :

Test-NetConnection 127.0.0.1 -Port 23721

Résultat attendu :

ComputerName     : 127.0.0.1
RemotePort       : 23721
TcpTestSucceeded : True

Ce résultat confirme que le port local est joignable. Il ne garantit pas, à lui seul, que l'ensemble de la chaîne OAuth fonctionne.

Étape 4 — Lancer l'authentification MCP GitLab

Ouvrir un second terminal dans code-server :

codex mcp login gitlab-http

Codex affiche une URL d'autorisation GitLab :

Authorize `gitlab-http` by opening this URL in your browser:
https://gitlab.darkmat.fr/oauth/authorize?...

Ouvrir cette URL dans le navigateur Windows.

S'authentifier sur GitLab puis autoriser l'application OAuth.

Après validation, le navigateur est redirigé vers une adresse de ce type :

http://127.0.0.1:23721/callback/<identifiant>?code=...

Ne pas partager cette URL complète : elle contient un code d'autorisation temporaire.

Étape 5 — Confirmer la réussite

Le navigateur doit afficher :

Authentication complete. You may close this window.

Dans le terminal code-server :

Successfully logged in to MCP server 'gitlab-http'.

Ces deux messages confirment que le callback OAuth a été reçu et que Codex a terminé l'authentification.

4. Vérifier le fonctionnement du MCP GitLab

4.1. Vérifier la configuration

Dans code-server :

codex mcp list

Puis :

codex mcp get gitlab-http

Le MCP doit être activé et déclaré avec l'URL :

https://gitlab.darkmat.fr/api/v4/mcp

4.2. Vérifier depuis Codex

Démarrer une nouvelle session interactive :

codex

Puis saisir :

/mcp

Vérifier que gitlab-http apparaît avec un statut connected et que des outils sont disponibles.

4.3. Tester un appel réel

Demander à Codex :

Utilise le MCP GitLab pour lister les projets auxquels
mon compte GitLab a accès.

Si Codex utilise les outils MCP GitLab et retourne les projets, la connexion est opérationnelle.

4.4. Supprimer l'ancienne configuration mcp-remote

Si l'ancienne connexion gitlab basée sur mcp-remote est encore présente :

codex mcp list

Une fois la connexion gitlab-http vérifiée, supprimer uniquement l'ancienne :

codex mcp remove gitlab

Ne pas supprimer gitlab-http.

5. Nettoyage après authentification

Lorsque l'authentification a réussi :

Fermer la fenêtre de callback dans Chrome.
Arrêter le tunnel SSH Windows avec Ctrl+C.
Arrêter socat avec Ctrl+C.

Les identifiants OAuth sont normalement conservés par Codex et peuvent être réutilisés pour les connexions suivantes.

Le tunnel SSH et socat ne sont nécessaires que lorsqu'une authentification interactive OAuth doit à nouveau être effectuée.

Un simple redémarrage de Codex ne nécessite donc normalement pas de relancer ces deux services.

6. Réauthentification — Procédure rapide

Si le MCP GitLab nécessite une nouvelle authentification :

1. Dans code-server, lancer socat :

socat \
  TCP-LISTEN:23721,bind=0.0.0.0,reuseaddr,fork \
  TCP:127.0.0.1:23722

2. Dans PowerShell Windows, ouvrir le tunnel SSH :

ssh -N -p 3307 -L 127.0.0.1:23721:127.0.0.1:23720 darkmat@<DOMAINE_SSH>

3. Dans code-server, lancer le login GitLab :

codex mcp login gitlab-http

4. Dans le navigateur Windows :

Ouvrir l'URL d'autorisation GitLab.
Valider l'accès OAuth.
Attendre Authentication complete.

5. Vérifier :

codex mcp list

Puis /mcp dans une nouvelle session Codex.

6. Arrêter le tunnel SSH et socat.

7. Dépannage

Erreur ERR_CONNECTION_REFUSED dans Chrome

Si le navigateur est redirigé vers :

http://127.0.0.1:38317/callback/...

Codex utilise probablement un port OAuth dynamique.

Vérifier :

mcp_oauth_callback_port = 23722
mcp_oauth_callback_url = "http://127.0.0.1:23721/callback"

Ces paramètres doivent figurer au niveau racine de config.toml.

Relancer ensuite l'authentification.

Erreur sur 127.0.0.1:23721

Vérifier successivement :

Sur Windows :

Test-NetConnection 127.0.0.1 -Port 23721

Sur Ubuntu Server :

docker port code-server

Vérifier que Docker expose :

23721/tcp -> 127.0.0.1:23720

Dans code-server :

command -v socat
ss -lntp

Vérifier que socat écoute sur 23721 et que Codex écoute sur 127.0.0.1:23722 pendant l'authentification.

Erreur Address already in use

Un autre processus utilise déjà l'un des ports.

Vérifier dans code-server :

ss -lntp | grep -E '23721|23722'

Sous Windows :

Get-NetTCPConnection -LocalPort 23721 -ErrorAction SilentlyContinue

Fermer l'ancien tunnel SSH ou le relais socat s'ils sont encore actifs, sans interrompre un service non identifié.

MCP GitLab : failed (0 tools)

Ce message signifie que Codex n'a pas pu initialiser les outils du serveur.

Vérifier :

codex mcp list
codex mcp get gitlab-http

Causes possibles :

Authentification OAuth expirée ou invalide.
Endpoint GitLab MCP indisponible.
Problème réseau entre le conteneur et GitLab.
Permissions GitLab insuffisantes.
Problème de compatibilité MCP.

Si nécessaire, refaire la procédure OAuth complète.

Le tunnel SSH ne démarre pas

Vérifier que le port SSH 3307 est accessible et que la redirection de la box est correcte.

Pour obtenir davantage d'informations :

ssh -v -N -p 3307 -L 127.0.0.1:23721:127.0.0.1:23720 darkmat@<DOMAINE_SSH>

Vérifier également que le serveur SSH autorise les redirections TCP (AllowTcpForwarding).

8. Rappels de sécurité

Ne jamais exposer les ports OAuth 23720, 23721 ou 23722 sur Internet.
Conserver le mapping Docker sur 127.0.0.1:23720.
Utiliser SSH comme transport chiffré entre Windows et Ubuntu.
Préférer l'authentification SSH par clé.
Ne pas partager les URL OAuth complètes contenant un paramètre code.
Protéger les identifiants OAuth conservés par Codex.
Éviter d'autoriser inutilement des opérations d'écriture GitLab via les outils MCP.

9. Références

En résumé : Docker et Codex se configurent une seule fois. Pour toute nouvelle authentification interactive, il suffit de lancer socat, d'ouvrir le tunnel SSH Windows, puis d'exécuter codex mcp login gitlab-http. Aucun autre port n'est à ouvrir sur la box Internet.

Configurer le MCP GitLab sur code-server

Configurer le MCP GitLab sur code-server

1. Objectif

Architecture

Tableau des ports

2. Configuration initiale (une seule fois)

2.1. Configurer Docker Compose

2.2. Configurer Codex

3. Procédure d'authentification OAuth

Étape 1 — Lancer socat dans code-server

Étape 2 — Lancer le tunnel SSH depuis Windows

Étape 3 — Vérifier le tunnel SSH

Étape 4 — Lancer l'authentification MCP GitLab

Étape 5 — Confirmer la réussite

4. Vérifier le fonctionnement du MCP GitLab

4.1. Vérifier la configuration

4.2. Vérifier depuis Codex

4.3. Tester un appel réel

4.4. Supprimer l'ancienne configuration mcp-remote

5. Nettoyage après authentification

6. Réauthentification — Procédure rapide

7. Dépannage

Erreur ERR_CONNECTION_REFUSED dans Chrome

Erreur sur 127.0.0.1:23721

Erreur Address already in use

MCP GitLab : failed (0 tools)

Le tunnel SSH ne démarre pas

8. Rappels de sécurité

9. Références

No Comments