Skip to content

Protéger un serveur MCP AdonisJS avec Sesame

Dans mon article sur adonis-mcp 2.0, je parlais du protocole et de ce qui a changé cet été. Il restait une question : comment brancher ce serveur sur Claude Desktop ou ChatGPT sans le laisser ouvert à tout le monde ?

Ces clients passent par OAuth. Ils découvrent le serveur d'autorisation, s'enregistrent, puis demandent à l'utilisateur de se connecter et de donner son accord. AdonisJS propose maintenant Sesame, un serveur OAuth 2.1 qui s'installe directement dans l'application. J'ai monté un petit projet de démo pour faire fonctionner les deux ensemble.

Le code est disponible sur GitHub : batosai/adonis-mcp-sesame. Je suis parti du starter AdonisJS avec l'authentification par session. L'historique tient en deux commits qu'on peut suivre dans l'ordre de l'article : le serveur MCP d'abord, sa protection ensuite.

Le serveur MCP ​

On installe le package :

sh
node ace add @jrmc/adonis-mcp

La commande crée config/mcp.ts et enregistre les providers et les commandes. La configuration minimale se limite au nom et à la version du serveur :

ts
import { defineConfig } from '@jrmc/adonis-mcp'

export default defineConfig({
  name: 'adonis-mcp-server',
  version: '1.0.0',
})

Pour la démo, un seul outil, généré avec node ace make:mcp-tool hello_world :

ts
import type { ToolContext } from '@jrmc/adonis-mcp/types/context'
import type { BaseSchema } from '@jrmc/adonis-mcp/types/method'

import { Tool } from '@jrmc/adonis-mcp'
import vine from '@vinejs/vine'

type Schema = BaseSchema<{
  name: { type: 'string' }
}>

const vineSchema = vine.object({
  name: vine.string().meta({
    description: 'Nom de la personne à saluer',
  }),
})

export default class HelloWorldTool extends Tool<Schema> {
  name = 'hello_world'
  title = 'Hello World'
  description = 'Dit bonjour à la personne nommée'

  async handle({ args, response }: ToolContext<Schema>) {
    return response.text(`Hello, ${args?.name}`)
  }

  schema() {
    return vine.create(vineSchema).toJSONSchema() as Schema
  }
}

Le schéma est écrit avec VineJS puis converti en JSON Schema. La description passée dans meta() part avec lui jusqu'au client, c'est elle qui explique au modèle ce qu'il doit mettre dans ce paramètre quand il décide d'appeler l'outil.

Il reste à déclarer la route :

ts
router.mcp().use(middleware.mcp())

Le middleware mcp vérifie le Content-Type et gère l'en-tête MCP-Session-Id pour les clients qui utilisent encore les anciennes versions du protocole. Avec la version 2026-07-28, la requête passe directement.

Comme les clients MCP n'envoient pas de jeton CSRF, il faut exclure /mcp dans config/shield.ts.

Pour tester en local, node ace mcp:inspector lance l'inspecteur MCP, qui lit sa configuration dans .mcp-inspector.json :

json
{
  "mcpServers": {
    "adonis-mcp-http": {
      "type": "http",
      "url": "http://localhost:3333/mcp",
      "protocolEra": "modern"
    }
  }
}

À ce stade, l'outil répond. Le souci, c'est que n'importe qui peut l'appeler : il suffit de connaître l'URL.

Sesame comme serveur d'autorisation ​

On installe Sesame de la même façon :

sh
node ace add @adonisjs/sesame

La commande ajoute les migrations des tables OAuth : clients, codes d'autorisation, jetons d'accès, jetons de rafraîchissement, autorisations accordées et demandes en attente. Voici ma configuration :

ts
import env from '#start/env'
import { defineConfig, stores } from '@adonisjs/sesame'
import type { InferScopes } from '@adonisjs/sesame/types'

const sesameConfig = defineConfig({
  issuer: env.get('APP_URL'),
  store: stores.lucid(),

  scopes: {
    'mcp:tools': 'Utiliser les tools MCP',
  },
  defaultScopes: ['mcp:tools'],

  grantTypes: ['authorization_code', 'refresh_token'],

  accessTokenTtl: '1h',
  refreshTokenTtl: '30d',
  authorizationCodeTtl: '10m',

  loginPage: '/login',
  consentPage: '/oauth/consent',

  allowDynamicRegistration: true,
  allowPublicRegistration: true,

  clientIdMetadataDocuments: false,
})

export default sesameConfig

declare module '@adonisjs/sesame/types' {
  interface SesameScopes extends InferScopes<typeof sesameConfig> {}
}

Un seul scope, mcp:tools, attribué par défaut. L'issuer reprend APP_URL : il doit correspondre à l'adresse publique de l'application, sinon les clients refusent les métadonnées.

Le point important pour MCP, c'est l'enregistrement dynamique. Je ne connais pas à l'avance les clients qui vont se connecter, je ne peux donc pas leur créer un client_id à la main. Avec allowDynamicRegistration et allowPublicRegistration, ils s'enregistrent eux-mêmes sur /oauth/register.

Côté routes :

ts
router
  .group(() => {
    sesame.registerRoutes()
  })
  .prefix('/oauth')

sesame.registerDiscoveryRoutes()
sesame.registerProtectedResource({ resource: '/mcp', scopes: ['mcp:tools'] })

registerRoutes() déclare les endpoints OAuth (authorize, token, register, revoke, introspect, etc.). registerDiscoveryRoutes() publie /.well-known/oauth-authorization-server. Quant à registerProtectedResource(), elle publie /.well-known/oauth-protected-resource, le document qui dit au client que /mcp est protégé et vers quel serveur d'autorisation se tourner pour obtenir un jeton.

C'est grâce à ces deux fichiers que le client se débrouille seul. Il appelle /mcp, reçoit une 401 avec un en-tête WWW-Authenticate qui pointe vers les métadonnées de la ressource. Il remonte alors jusqu'au serveur d'autorisation, s'enregistre et lance le flux.

Protéger la route MCP ​

Sesame fournit un guard pour @adonisjs/auth. J'en déclare un nouveau à côté du guard web, dans config/auth.ts :

ts
mcp: oauthGuard({
  provider: oauthUserProvider({ model: () => import('#models/user') }),
  resource: '/mcp',
  requireAudience: true,
}),

Avec requireAudience, le guard n'accepte que les jetons émis pour la ressource /mcp. Un jeton obtenu pour une autre API de l'application ne passera pas.

Après avoir enregistré les middlewares scopes et anyScope de Sesame dans start/kernel.ts, la route MCP devient :

ts
router
  .mcp()
  .use([
    middleware.auth({ guards: ['mcp'] }),
    middleware.scopes({ guard: 'mcp', scopes: ['mcp:tools'] }),
    middleware.mcp(),
  ])

L'ordre compte : on authentifie, on vérifie le scope, puis on passe la main au serveur MCP.

Connexion et consentement ​

Quand le client lance l'autorisation, Sesame envoie l'utilisateur sur /login s'il n'est pas connecté, puis sur /oauth/consent.

Pour la page de connexion, il faut garder la demande en cours. Sesame redirige vers /login avec les paramètres OAuth dans l'URL. Je les récupère dans le contrôleur et je les place dans un champ caché du formulaire :

ts
async create({ view, request }: HttpContext) {
  const authorizationQuery = request.input('client_id') ? request.parsedUrl.query : null
  return view.render('pages/auth/login', { authorizationQuery })
}

Après la connexion, je renvoie vers /oauth/authorize avec ces paramètres :

ts
const authorizationQuery = request.input('authorization_query')
if (typeof authorizationQuery === 'string' && authorizationQuery.length > 0) {
  return response.redirect().toPath(`/oauth/authorize?${authorizationQuery}`)
}

Je ne redirige que vers cette route. Accepter une URL de retour libre ouvrirait une redirection exploitable.

J'ai aussi dû passer forwardQueryString à false dans config/app.ts. Sinon, les redirections reprennent la query string de la requête en cours et les paramètres OAuth se retrouvent là où on ne les attend pas.

La page de consentement est la seule partie à écrire soi-même. Le contrôleur ne gère que l'affichage, Sesame traite la soumission :

ts
export default class OauthConsentController {
  async show({ request, auth, view }: HttpContext) {
    const user = auth.getUserOrFail()
    const authToken = String(request.input('auth_token', ''))

    const pending = await sesame.findPendingAuthorizationRequest({
      token: authToken,
      userId: String(user.id),
    })

    if (!pending) {
      return view.render('pages/oauth/consent', { expired: true })
    }

    const client = await sesame.findClient(pending.clientId)

    return view.render('pages/oauth/consent', {
      expired: false,
      authToken,
      clientName: client?.name ?? pending.clientId,
      redirectHost: new URL(pending.redirectUri).host,
      scopes: pending.scopes,
    })
  }
}

La vue affiche le nom du client, le domaine de redirection et les scopes demandés, avec deux boutons. Le formulaire poste sur /oauth/consent en renvoyant auth_token, avec accept=1 quand l'utilisateur clique sur « Autoriser ».

J'affiche le domaine de redirection parce qu'avec l'enregistrement dynamique, n'importe qui peut déclarer un client et lui donner le nom qu'il veut. Le domaine permet à l'utilisateur de voir où partira le code d'autorisation.

Côté CSRF, j'exclus seulement les endpoints appelés de serveur à serveur :

ts
exceptRoutes: [
  '/mcp',
  '/oauth/token',
  '/oauth/introspect',
  '/oauth/revoke',
  '/oauth/register',
],

Le POST /oauth/consent vient du navigateur de l'utilisateur, il garde sa protection.

Brancher Claude Desktop ou ChatGPT ​

Ces deux clients appellent le serveur MCP depuis leur propre infrastructure : localhost ne fonctionnera pas. Il faut exposer l'application en HTTPS, avec un tunnel comme cloudflared ou ngrok par exemple. L'URL publique va dans APP_URL.

Ensuite, on ajoute un connecteur personnalisé avec l'URL https://mon-domaine.fr/mcp, dans les réglages de Claude Desktop ou en mode développeur dans ChatGPT. Le client s'enregistre, ouvre la page de connexion, puis l'écran de consentement. Une fois l'accès autorisé, hello_world apparaît dans la liste des outils.

La suite ​

Le jeton donne accès à l'utilisateur dans le contexte MCP. adonis-mcp sait déjà transmettre auth et bouncer aux outils, il reste à le brancher dans le middleware pour que chaque outil agisse au nom de l'utilisateur connecté, avec les mêmes policies que le reste de l'application. Ce sera le sujet d'un prochain article.

En attendant, le projet complet est sur GitHub pour ceux qui veulent le lancer chez eux.