Tests de connexion et d’accès via MCP Jam : None, Bearer, OAuth with credentials, Default OAuth

1. MCP Jam comme laboratoire pour l’autorisation

MCP Jam n’est pas « encore un outil bizarre », mais votre banc de laboratoire qui sait jouer le rôle d’un client MCP. En substance, c’est un émulateur du comportement de ChatGPT face à un serveur MCP : il sait lire .well-known/oauth-protected-resource, lancer un flux OAuth, attacher les jetons aux requêtes et montrer précisément ce qui a mal tourné.

Un point pratique très important : si vous réussissez le flux Default OAuth dans MCP Jam, vous êtes prêts à environ 80 % pour l’intégration avec une vraie app ChatGPT. Tout ce que fait ChatGPT lors de la liaison de compte (linking), Jam sait déjà le faire, avec des journaux et des boutons plus transparents.

Dans le cours précédent, nous avons configuré l’autorisation de base pour notre serveur MCP d’apprentissage GiftGenius : nous avons choisi la méthode de vérification du jeton (JWT ou introspection), implémenté .well-known/oauth-protected-resource et un middleware qui protège les outils. Voyons maintenant comment tout cela se comporte dans MCP Jam selon les différents modes d’autorisation.

Notre objectif dans ce cours est d’apprendre à :

• basculer consciemment les modes d’autorisation dans Jam (None, Bearer, OAuth with credentials, Default OAuth) ;
• comprendre ce que Jam envoie exactement au serveur MCP dans chaque mode ;
• diagnostiquer quelle partie du système est en panne : MCP Server, Auth Server ou les métadonnées ;
• vérifier que les outils protégés ne fonctionnent qu’avec un jeton, tandis que les outils ouverts fonctionnent aussi sans jeton.

2. Notre serveur MCP d’apprentissage : ce que nous testons

Pour éviter de parler abstraitement, rappelons brièvement le contexte. Nous poursuivons avec notre application d’apprentissage GiftGenius — une app ChatGPT qui aide à choisir des cadeaux et affiche à l’utilisateur ses commandes et listes de souhaits.

Côté serveur MCP, nous avons déjà :

• un outil ouvert, par exemple search_gifts — il peut être appelé anonymement ;
• un outil protégé, par exemple list_user_orders — il ne doit fonctionner que pour un utilisateur authentifié et exiger le scope mcp:tools.

Le serveur sait :

• publier .well-known/oauth-protected-resource ;
• vérifier le jeton (JWT ou via introspection — vous avez choisi une approche lors du cours précédent) ;
• extraire du jeton sub (ID utilisateur), scope, aud et les transmettre aux handlers des outils.

Un middleware typique de vérification de jeton en Node.js/TypeScript peut ressembler à ceci :

// middleware/auth.ts
export function requireScope(requiredScope: string) {
  return async (req: any, res: any, next: () => void) => {
    const header = req.headers["authorization"];
    if (!header?.startsWith("Bearer ")) {
      res
        .status(401)
        .set(
          "WWW-Authenticate",
          `Bearer realm="mcp", resource_metadata="${process.env.BASE_URL}/.well-known/oauth-protected-resource", scope="${requiredScope}"`
        )
        .json({ error: "unauthorized" });
      return;
    }

    // ici, vous vérifiez déjà le jeton (signature, exp, aud, scope...)
    // et placez le résultat dans req.user
    next();
  };
}

Ce middleware sera utilisé avant les outils protégés MCP. S’il n’y a pas de jeton — nous renvoyons 401 et un WWW-Authenticate correct avec resource_metadata, comme l’exige la spécification MCP Authorization. Vous avez déjà réalisé une analyse détaillée de la vérification de jeton et des fonctions auxiliaires dans le cours précédent, nous l’utilisons ici comme acquis.

3. Modes d’autorisation dans MCP Jam : vue d’ensemble

MCP Jam propose plusieurs modes d’autorisation pour se connecter à un serveur MCP. Ils correspondent aux schémas OAuth typiques : de l’absence totale de jeton au flux Authorization Code + PKCE complet.

En bref :

1. None (No Auth) — Jam n’ajoute pas du tout l’en‑tête Authorization. C’est un accès anonyme. Convient aux serveurs MCP ouverts et à la vérification que les ressources fermées refusent correctement avec 401 et WWW-Authenticate.
2. Bearer Token — Jam ajoute Authorization : Bearer <jeton>, que vous saisissez manuellement dans l’interface. Convient aux vérifications rapides : le jeton a déjà été obtenu quelque part (curl, interface Keycloak), et vous voulez tester le comportement de la ressource MCP.
3. OAuth with credentials (Client Credentials) — Jam obtient lui‑même un jeton via client_credentials auprès de l’Auth Server, en utilisant le Client ID et le Secret indiqués. C’est le mode « client confidentiel », plus proche d’une autorisation serveur‑à‑serveur sans intervention de l’utilisateur.
4. Default OAuth (Authorization Code + PKCE) — le mode principal pour les clients de type ChatGPT (public client sans secret). Jam lit resource_metadata, trouve l’Auth Server, lance le navigateur avec /authorize, exécute le flux PKCE et obtient un jeton utilisateur.

Pour plus de clarté, résumons ceci dans un tableau.

Nous allons maintenant passer en revue chaque mode et voir comment faire passer notre serveur MCP GiftGenius à travers eux.

4. Mode None : vérifier que le serveur refuse correctement

Commençons par le mode le plus simple : aucune autorisation.

Dans MCP Jam, vous choisissez votre serveur (par exemple, http://localhost:4000/mcp) et, dans les paramètres de connexion, vous sélectionnez le mode d’autorisation None.

Ce qui se passe alors :

• Jam établit une connexion MCP ;
• lors de l’appel d’un outil, il n’ajoute pas l’en‑tête Authorization ;
• vous pouvez appeler n’importe quel outil ouvert (par exemple, search_gifts) ;
• lors de l’appel d’un outil protégé (par exemple, list_user_orders), votre serveur doit répondre 401 Unauthorized.

Il est important que pour ce 401, le serveur ajoute un WWW-Authenticate correct. Exemple de réponse avec champs supplémentaires realm et scope, proche de ce que recommandent OpenAI et la spécification MCP Authorization :

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp",
  resource_metadata="https://giftgenius.example.com/.well-known/oauth-protected-resource",
  scope="mcp:tools"
Content-Type: application/json

{"error": "unauthorized"}

En voyant cette réponse, Jam comprend : la ressource est protégée, voici où récupérer les métadonnées (resource_metadata) et quels scopes sont attendus. En mode None, il vous affiche simplement l’erreur, mais en mode Default OAuth, il suivra automatiquement le resource_metadata indiqué et lancera le flux OAuth.

Du point de vue du débogage, en mode None vous vérifiez :

• que les outils ouverts fonctionnent sans jeton ;
• que les outils protégés ne s’exécutent jamais anonymement ;
• que l’en‑tête WWW-Authenticate est conforme à la spécification (inclut Bearer et resource_metadata).

Cela semble trivial, mais un grand nombre de problèmes commencent par un 401 renvoyé sans WWW-Authenticate ou avec un paramètre erroné (par exemple, l’ancien resource_metadata_uri au lieu de l’actuel resource_metadata).

5. Mode Bearer Token : test rapide de la logique du Resource Server

Étape suivante — un mode où vous avez déjà un jeton valide (obtenu en dehors de Jam) et vous souhaitez tester la logique du Resource Server : accepte‑t‑il/rejette‑t‑il correctement ce jeton, gère‑t‑il correctement le scope et l’audience, et associe‑t‑il sub à l’utilisateur de votre service.

Dans MCP Jam, basculez le mode sur Bearer Token et collez dans le champ du jeton, par exemple :

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Désormais, Jam ajoutera à chaque requête MCP l’en‑tête :

Authorization: Bearer eyJhbGciOi...

Votre serveur MCP reçoit la requête, passe par le middleware requireScope("mcp:tools"), décode le JWT et vérifie les claims. Un code de vérification typique peut s’écrire, en version simplifiée, comme suit :

// auth/verifyToken.ts
import jwt from "jsonwebtoken";

export function verifyToken(header: string) {
  const token = header.replace("Bearer ", "");
  const payload = jwt.verify(token, process.env.JWT_PUBLIC_KEY!);
  // ici, on peut vérifier aud, scope, etc.
  return payload as { sub: string; scope?: string };
}

Et l’utiliser dans le middleware :

// à l'intérieur de requireScope
const payload = verifyToken(header);
if (!payload.scope?.includes(requiredScope)) {
  res.status(403).json({ error: "insufficient_scope" });
  return;
}
(req as any).user = { id: payload.sub };
next();

En mode Bearer, vous pouvez expérimenter :

• coller un jeton sans le scope requis et vérifier que le serveur répond 403/401 ;
• coller un jeton avec une aud incorrecte et voir que le serveur le rejette ;
• coller un jeton expiré pour vérifier l’erreur invalid_token.

C’est le mode de « test de charge » local de la logique du Resource Server sans impliquer de connexion UI ni de PKCE. Tout ce que vous vérifiez ici s’appliquera à l’identique aux jetons que ChatGPT ou Jam obtiendront en mode Default OAuth.

6. Mode OAuth with credentials (Client Credentials) : jeton « au nom de l’application »

Passons maintenant à un mode plus rare, mais utile pour comprendre : OAuth with credentials, c’est‑à‑dire le grant client_credentials. Dans Jam, vous indiquez :

• Client ID
• Client Secret
• les scopes nécessaires (par exemple, mcp:tools)

Jam effectue une requête vers le token_endpoint de votre Auth Server de la forme :

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=<ID>&
client_secret=<SECRET>&
scope=mcp:tools

L’Auth Server délivre un jeton où sub désigne généralement le client lui‑même (par exemple, sub = "mcp-jam-test-client") et non un utilisateur particulier. Jam commence à utiliser ce jeton comme un Bearer classique.

À quoi cela peut‑il servir dans le monde MCP :

• outils de service/admin non liés à un utilisateur spécifique (par exemple, export de journaux, health‑check, support) ;
• vérifier que le serveur MCP sait distinguer les jetons utilisateurs des jetons « client », si votre logique métier en tient compte.

Dans le contexte des apps ChatGPT, ce mode n’est généralement pas utilisé, car ChatGPT, en tant que public client, ne stocke pas de secrets (et un public client ne doit pas avoir de client_secret par définition). Mais dans Jam, il aide à voir la différence entre :

• « J’ai simplement fourni un jeton prêt à l’emploi » (mode Bearer) ;
• « Jam est allé chercher le jeton avec des identifiants client » (OAuth with credentials).

Sur un serveur d’apprentissage, vous pouvez, par exemple, créer un MCP‑tool spécial admin_list_all_orders, disponible uniquement avec un jeton ayant grant_type=client_credentials et le rôle correspondant. Ce n’est pas obligatoire aujourd’hui, mais c’est une expérience utile.

7. Mode Default OAuth : Authorization Code + PKCE complet, comme chez ChatGPT

Voici maintenant la vedette : Default OAuth. C’est ce mode qui se rapproche le plus de ce que fait ChatGPT lors de la liaison du compte de votre app. Le client lit resource_metadata, va vers l’Auth Server, ouvre la page de connexion pour l’utilisateur, récupère un authorization code et l’échange contre un access token via Authorization Code + PKCE S256.

Décomposons la séquence des étapes. Pour plus de clarté — un diagramme.

sequenceDiagram
    participant Jam as MCP Jam (Client)
    participant RS as MCP Server (Resource)
    participant PRM as /.well-known/oauth-protected-resource
    participant AS as Auth Server (Keycloak/Auth0)
    
    Jam->>RS: Appel d’un outil protégé (sans jeton)
    RS-->>Jam: 401 + WWW-Authenticate (resource_metadata=PRM)
    Jam->>PRM: GET /.well-known/oauth-protected-resource
    PRM-->>Jam: JSON avec resource, authorization_servers, scopes_supported...
    Jam->>AS: GET /authorize?client_id=...&code_challenge=...&scope=...
    Note right of AS: L’utilisateur se connecte et donne son consentement
    AS-->>Jam: redirection avec authorization_code
    Jam->>AS: POST /token (code + code_verifier)
    AS-->>Jam: { access_token, scope, expires_in, ... }
    Jam->>RS: Appel d’un outil avec Authorization: Bearer <access_token>
    RS-->>Jam: Résultat de l’outil avec succès

Ce que vous devez vérifier dans ce mode :

1. Une réponse 401/WWW-Authenticate correcte du serveur MCP. Si le serveur ne renvoie pas resource_metadata ou renvoie une URL incorrecte, Jam ne pourra pas lire le PRM ni lancer le flux OAuth.
2. Un document valide .well-known/oauth-protected-resource. Il doit contenir des resource, authorization_servers, scopes_supported, etc. corrects afin que Jam sache vers où aller chercher les jetons et quels scopes demander.
3. Une configuration correcte de l’Auth Server.
   • Authorization Code Flow avec PKCE S256 activé.
   • Le Client ID correspond à ce qui est attendu dans le PRM (ou est enregistré via DCR — Dynamic Client Registration).
   • Le Redirect URI dans l’Auth Server correspond exactement à celui utilisé par Jam.
4. PKCE S256. Jam forme un code_challenge et s’attend à ce que l’Auth Server prenne en charge la méthode S256. Si PKCE est désactivé ou si seul le mode plain est pris en charge, le flux échouera.
5. Scopes et audience. L’Auth Server doit émettre un jeton avec le aud requis et les scopes demandés (mcp:tools, etc.), et le serveur MCP doit les vérifier.

À l’issue d’un Default OAuth réussi, vous obtiendrez :

• dans Jam — une connexion au serveur MCP où l’outil protégé list_user_orders renvoie les données correctes pour l’utilisateur avec lequel vous vous êtes connecté à l’Auth Server ;
• dans les journaux de l’Auth Server — un authorize et un échange de token réussis ;
• dans les journaux du serveur MCP — une validation de jeton réussie et l’extraction de sub.

Pour le débogage, il est souvent utile d’ajouter un simple logger dans le handler de l’outil afin de vérifier que vous voyez bien le userId issu du jeton :

// dans le handler de l’outil MCP list_user_orders
export async function listUserOrders(args: any, context: any) {
  const user = context.user as { id: string };
  console.log("[MCP] listUserOrders for user", user.id);
  // ensuite, vous renvoyez les commandes de cet utilisateur
}

8. Où ça casse : diagnostic par mode

Discutons maintenant de la manière d’identifier, à partir des symptômes dans MCP Jam, où se situe exactement le problème : dans le serveur MCP, dans l’Auth Server ou dans les métadonnées. Cette section est une sorte de check‑list de diagnostic par mode.

Si en mode None :

Vous appelez un outil protégé, le serveur renvoie :

• 200 OK et exécute l’action même sans jeton — cela signifie que vous n’avez pas de vérification de jeton avant cet outil. Il faut ajouter un middleware ou une vérification des scopes.
• 401, mais sans WWW-Authenticate ou avec un resource_metadata incorrect — Jam ne saura pas où aller chercher les métadonnées, et ne pourra pas lancer Default OAuth. Corrigez l’en‑tête d’après l’exemple ci‑dessus.

Si en mode Bearer Token :

• Jam reçoit systématiquement 401/403 même avec un jeton dont vous êtes sûr qu’il est valide en appel direct (via curl ou Postman). Très probablement, quelque chose cloche dans la logique du Resource Server : vérification incorrecte de aud/scope ou clé publique inappropriée pour la signature du JWT.
• Si le jeton Bearer fonctionne dans Jam mais pas ensuite en Default OAuth — le problème n’est pas dans le serveur MCP, mais dans l’Auth Server ou le PRM : le jeton obtenu via Default OAuth diffère par scope/aud de celui que vous aviez testé à la main.

Si en mode OAuth with credentials :

• Si Jam ne peut pas obtenir de jeton (erreur à l’étape /token) — cherchez la cause dans la configuration du client sur l’Auth Server (secret incorrect, client_credentials non autorisé ou scope interdit).
• Si le jeton existe, mais que le serveur MCP le rejette — il est possible que votre serveur attende un sub utilisateur (email/ID utilisateur), alors que le jeton ne contient que l’identifiant du client. Ou bien aud/scope ne correspondent pas aux attentes.

Si en mode Default OAuth :

C’est le scénario le plus riche en pièges. Problèmes fréquents :

• Redirect URI incorrects. L’Auth Server se plaint de invalid_redirect_uri ou ne délivre simplement pas de code. Assurez‑vous que l’URI de Jam est enregistré dans la configuration du client IdP, sans slash superflu ni coquille.
• Absence de PKCE ou PKCE non pris en charge. Si l’Auth Server exige PKCE et que Jam (ou une ancienne version) n’envoie pas de code_challenge, ou inversement — Jam envoie S256 et l’IdP ne supporte pas cette méthode, vous verrez invalid_request.
• Scopes non concordants. Dans le PRM vous avez déclaré mcp:tools, mais le client dans l’IdP n’est autorisé qu’à openid, ou inversement — Jam demande plus de scopes que l’IdP n’est prêt à émettre.
• Audience (aud) incorrecte. Le jeton est délivré avec un aud différent de celui qu’attend le serveur MCP (par exemple, l’URL d’une autre ressource). Le serveur le rejettera à juste titre.

Il est très important d’apprendre à consulter les journaux de trois endroits :

• MCP Jam — erreurs lors de l’analyse du PRM et des requêtes HTTP vers l’Auth Server ;
• Auth Server — journaux de /authorize et /token indiquant ce qu’il refuse ;
• Serveur MCP — raisons du rejet du jeton (invalid_token, insufficient_scope, wrong_audience).

9. Lien avec une app ChatGPT réelle

Pourquoi passer autant de temps à jouer avec Jam au lieu d’aller directement dans le Developer Mode de ChatGPT ? Parce que Jam est un véritable banc de laboratoire : il vous donne la main sur les modes d’autorisation et affiche tout l’enchaînement interne du flux.

Lorsque vous lancez Default OAuth dans Jam et que vous le menez à bien, vous confirmez en pratique :

• .well-known/oauth-protected-resource sur le serveur MCP est correct ;
• l’Auth Server (Keycloak/Auth0/…) est configuré correctement ;
• les rôles, scopes, audience et claims correspondent aux attentes ;
• le serveur MCP sait vérifier le jeton et le lier à l’utilisateur.

ChatGPT, connecté au même serveur MCP, fera la même chose : il lira le PRM, ira à l’Auth Server, obtiendra un jeton et commencera à appeler les outils avec Authorization : Bearer.

La différence, c’est que dans ChatGPT vous ne voyez que le résultat final (« compte lié avec succès » ou « quelque chose a mal tourné »), tandis que dans Jam — vous voyez tout le protocole et pouvez comprendre pas à pas ce qui cloche.

10. Mini‑pratique : test séquentiel de notre serveur MCP GiftGenius

Rassemblons tout dans un scénario simple et séquentiel que vous pouvez reproduire sur votre projet.

Commencez par lancer votre serveur MCP (par exemple, pnpm dev:mcp), et assurez‑vous que :

• il écoute sur http://localhost:4000/mcp (ou votre URL) ;
• l’endpoint /.well-known/oauth-protected-resource renvoie un JSON correct ;
• l’Auth Server (Keycloak) fonctionne et dispose d’un public client configuré pour Jam/ChatGPT.

Ensuite :

1. Mode None.
   Connectez Jam au serveur MCP sans autorisation. Vérifiez que :
   • search_gifts s’exécute ;
   • list_user_orders renvoie 401 avec un WWW-Authenticate correct.
2. Mode Bearer Token.
   Obtenez un access token via Keycloak (via l’UI ou curl). Injectez‑le dans Jam, appelez list_user_orders et assurez‑vous que :
   • avec un jeton valide l’outil s’exécute et renvoie les commandes de l’utilisateur en question ;
   • avec un jeton sans mcp:tools ou avec une autre aud — le serveur renvoie une erreur.
3. Mode OAuth with credentials.
   Si vous avez un client confidentiel : indiquez client_id et client_secret dans Jam, définissez le scope nécessaire, appelez un outil technique (par ex. admin_list_all_orders) et vérifiez que cela ne fonctionne qu’avec ce jeton de service.
4. Mode Default OAuth.
   Activez Default OAuth, appelez list_user_orders. Jam va :
   • recevoir 401 + WWW-Authenticate,
   • lire le PRM,
   • ouvrir le navigateur, où vous vous connecterez à Keycloak,
   • obtenir un jeton via Authorization Code + PKCE,
   • appeler l’outil MCP avec le jeton, après quoi vous verrez vos commandes dans la réponse.

Si les quatre modes fonctionnent comme prévu — félicitations, vous n’avez pas juste « bricolé quelque chose avec Keycloak », vous comprenez réellement comment tester et déboguer tout le flux d’autorisation.

11. Erreurs typiques avec MCP Jam et les tests d’autorisation

Dans la pratique, ces problèmes apparaissent souvent sous forme de schémas d’erreurs récurrents. Ci‑dessous — quelques scénarios typiques de « ce qu’il ne faut pas faire », afin que vous puissiez les reconnaître à leurs symptômes.

Erreur n° 1 : s’attendre à ce qu’un outil protégé fonctionne en mode None.
Parfois, un développeur lance Jam en mode None, appelle list_user_orders et s’étonne d’un 401, puis « par précaution » supprime la vérification du jeton côté serveur. Résultat : l’outil MCP commence à fonctionner anonymement, ce qui est totalement inacceptable pour des données personnelles et des scénarios commerce. Le mode None sert précisément à vérifier que le serveur refuse correctement sans jeton et renvoie WWW-Authenticate avec resource_metadata.

Erreur n° 2 : en‑tête WWW-Authenticate oublié ou incorrect.
Cas très répandu : le serveur renvoie 401 sans WWW-Authenticate ou avec l’ancien paramètre resource_metadata_uri. Jam (comme ChatGPT) ne sait alors pas où aller chercher les Protected Resource Metadata, et Default OAuth ne démarre tout simplement pas. Le minimum requis — WWW-Authenticate : Bearer resource_metadata="https://.../.well-known/oauth-protected-resource". Les champs realm et scope restent optionnels ; l’essentiel est de ne pas oublier resource_metadata.

Erreur n° 3 : ne tester que le mode Bearer et ignorer Default OAuth.
Le développeur obtient manuellement un jeton, le colle dans Jam, constate que tout fonctionne et considère la tâche terminée. Mais au moment de brancher le vrai ChatGPT, il s’avère que .well-known est incorrect, PKCE n’est pas pris en charge, le Redirect URI ne correspond pas, et la liaison échoue. Tester le mode Bearer — nécessaire, mais insuffisant. Il faut absolument exécuter Default OAuth, sinon vous ne testerez pas la moitié des réglages essentiels de l’Auth Server et du PRM.

Erreur n° 4 : utiliser client_credentials là où il faut un jeton utilisateur.
Parfois, à bout, un développeur active dans Jam le mode OAuth with credentials et commence à obtenir des jetons via client_credentials, puis à les utiliser pour des outils utilisateurs comme list_user_orders. Résultat : sub dans le jeton — c’est le client_id, et non un véritable utilisateur, et la logique métier se comporte étrangement (par exemple, affiche des données « globales » ou plante en tentant de trouver un utilisateur avec cet ID). Pour les scénarios ChatGPT avec de vrais utilisateurs, il faut Authorization Code + PKCE (Default OAuth), tandis que client_credentials convient uniquement aux tâches de service.

Erreur n° 5 : scopes et audience non alignés entre PRM, Auth Server et serveur MCP.
Dans .well-known/oauth-protected-resource, vous avez déclaré que la ressource est https://giftgenius.example.com et que les scopes pris en charge sont ["mcp:tools"]. L’Auth Server délivre au client un jeton sans aud, alors que le serveur MCP attend strictement aud = "https://giftgenius.example.com" et la présence de mcp:tools. Au final, le jeton obtenu via Default OAuth est rejeté par le serveur MCP, et vous perdez la demi‑journée à chercher une « magie ». Vérifiez toujours que PRM, la configuration du client dans l’IdP et la vérification dans le middleware du serveur MCP sont alignés sur audience et scope.

Erreur n° 6 : utiliser une ancienne version de MCP Jam.
La spécification MCP Authorization évolue activement, avec de nouveaux champs (resource_metadata, flux PKCE amélioré, outils de débogage). Si vous avez une ancienne version de Jam, elle peut ne pas comprendre les champs récents ou fonctionner avec d’anciens noms de paramètres. Cela mène à des bugs surréalistes : vous avez tout configuré selon le dernier RFC, et Jam ne sait simplement pas quoi en faire. Avant de désespérer, assurez‑vous que Jam est à jour.