Aller au contenu

MCP IA

Serveurs MCP pour agents IA

InTeach publie deux serveurs Model Context Protocol distants. Un agent IA (Microsoft 365 Copilot, Copilot Studio, Claude, ChatGPT, un client MCP maison) les appelle au nom d’une personne, avec un jeton OAuth 2 que cette personne a autorisé.

ServeurAdresseUtilisateursAccès
Édition pédagogiquehttps://api.example.com/mcp/authoringAdministrateurs et gestionnairesLecture, écriture ; suppression réservée aux superadministrateurs
Mes formationshttps://api.example.com/mcp/learningApprenants, et tout compte actif membre de l’organisationLecture seule

Remplacez https://api.example.com par l’adresse de l’API de votre environnement. L’administration l’affiche dans API et intégrations › Adresses de l’API.

Pour la procédure côté administrateur, voir Connecter un agent IA.

Transport

  • Streamable HTTP sans état, réponses JSON (pas de flux SSE). Seul POST est accepté ; une autre méthode reçoit 405 avec Allow: POST.
  • Chaque requête porte Authorization: Bearer <jeton>.
  • Un appel venant d’un navigateur avec un en-tête Origin non autorisé reçoit 403 {"error":"origin_not_allowed"}. Les appels de serveur à serveur, sans Origin, ne sont pas concernés.

Découverte OAuth

Un client MCP conforme découvre tout seul le serveur d’autorisation. Le premier appel sans jeton répond 401 :

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp/learning", scope="learning:read", error="invalid_token"
DocumentAdresse
Ressource protégée (RFC 9728), édition/.well-known/oauth-protected-resource/mcp/authoring
Ressource protégée (RFC 9728), apprenant/.well-known/oauth-protected-resource/mcp/learning
Serveur d’autorisation (RFC 8414)/.well-known/oauth-authorization-server

InTeach n’est pas un fournisseur OpenID Connect : il n’y a pas de /.well-known/openid-configuration.

Le document du serveur d’autorisation annonce :

ChampValeur
authorization_endpoint/oauth/authorize
token_endpoint/oauth/token
registration_endpoint/oauth/register
revocation_endpoint/oauth/revoke
response_types_supportedcode
grant_types_supportedauthorization_code, refresh_token (et client_credentials pour l’API publique)
token_endpoint_auth_methods_supportedclient_secret_basic, client_secret_post, none
code_challenge_methods_supportedS256
authorization_response_iss_parameter_supportedtrue

Enregistrer un client

Enregistrement dynamique (DCR)

POST /oauth/register (RFC 7591) accepte trois champs, et ignore les autres :

ChampRègle
redirect_uris1 à 10 adresses ; HTTPS, ou HTTP sur localhost, 127.0.0.1 ou [::1] ; ni fragment ni identifiants
client_name120 caractères au plus ; « Agent MCP » par défaut
token_endpoint_auth_methodclient_secret_basic (par défaut), client_secret_post, ou none pour un client public
curl -s https://api.example.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"Mon agent","redirect_uris":["http://127.0.0.1:33418/callback"],"token_endpoint_auth_method":"none"}'

Un client confidentiel reçoit son client_secret une seule fois, sans date d’expiration. Un client dynamique n’appartient à aucune organisation : l’organisation est celle du compte qui donne son consentement. Les clients dynamiques publics, ou jamais utilisés, sans autorisation active, sont effacés au bout de 30 jours. Les documents de métadonnées client (CIMD) ne sont pas pris en charge.

Client confidentiel créé par l’organisation

Un administrateur crée le client dans API et intégrations › Clients OAuth, avec l’usage Agent IA des apprenants ou Agent IA d’édition pédagogique, une à dix URI de redirection, et reçoit un secret (ics_…) affiché une fois. Ce client est lié à son organisation et exige le module API et intégrations. C’est le mode à retenir pour Microsoft 365 Copilot avec coffre OAuth et pour Copilot Studio en mode manuel.

Les secrets se renouvellent avec un recouvrement de 0 à 168 heures. L’usage d’un client ne change pas après sa création.

Autorisation

Flux authorization_code avec PKCE S256 obligatoire, y compris pour les clients confidentiels. Le code_challenge fait 43 caractères ; state est limité à 1 024 caractères.

GET /oauth/authorize
  ?response_type=code
  &client_id=…
  &redirect_uri=http://127.0.0.1:33418/callback
  &scope=learning:read
  &code_challenge=…&code_challenge_method=S256
  &state=…
  &resource=https://api.example.com/mcp/learning

L’URI de redirection doit correspondre exactement à une URI déclarée, sauf le port sur une adresse de bouclage (RFC 8252). Elle peut être omise si le client n’en déclare qu’une.

Le paramètre resource

Chaque jeton est lié à une ressource : un jeton du serveur apprenant est refusé par le serveur d’édition et par l’API publique, et inversement. Envoyez resource (RFC 8707) avec l’adresse exacte du serveur. Sans lui :

  1. un client d’organisation obtient la ressource de son usage ;
  2. un client dynamique obtient la ressource dont les scopes couvrent ceux demandés (openid, profile, email et offline_access sont ignorés) ;
  3. sans scope exploitable, la ressource par défaut de l’environnement s’applique, si elle est définie ;
  4. sinon, la demande échoue avec invalid_request.

Au point de jeton, un resource absent reprend celui du code ; un resource différent est refusé.

Consentement

  • Serveur d’édition : la page Connecter un agent à InTeach s’ouvre dans l’administration. La lecture est toujours accordée ; la personne coche Autoriser la création et la modification pour content:write, et un superadministrateur peut ajouter Autoriser les suppressions depuis l’agent.
  • Serveur apprenant : la page Connecter un agent IA s’ouvre dans l’application apprenant de l’organisation. Pour un client dynamique, l’apprenant saisit d’abord l’identifiant de son organisation (20 recherches par minute et par adresse IP).
  • La demande de consentement vit 10 minutes et se lie au premier compte qui l’ouvre. Un refus renvoie error=access_denied avec iss et state.

Scopes

ScopeServeurEffet
learning:readApprenantLire ses formations, leur description et sa progression
content:readÉditionLire contenus, médias et plannings. Toujours requis
content:writeÉditionCréer, modifier, réordonner, publier, importer des médias
content:deleteÉditionConfirmer une suppression. Exige content:write et un superadministrateur, avec un client dynamique

Sans scope, le serveur apprenant accorde learning:read, et le serveur d’édition propose les trois scopes, que l’écran de consentement réduit. Un client ne peut jamais élargir ses scopes au consentement ni au rafraîchissement.

Jetons

ÉlémentDurée et règles
Code d’autorisation60 secondes, usage unique. Une réutilisation révoque l’autorisation
Jeton d’accès15 minutes, opaque, sans dépasser l’échéance de l’autorisation
Jeton de rafraîchissementTournant à chaque usage. Une réutilisation révoque l’autorisation
Autorisation30 jours, non prolongée par le rafraîchissement

Les droits sont recontrôlés à chaque appel et à chaque rafraîchissement : compte suspendu ou supprimé, rôle changé, organisation fermée, module désactivé ou client révoqué coupent l’accès (401 invalid_token, puis invalid_grant au rafraîchissement).

Révocation

  • Le client révoque avec POST /oauth/revoke (jeton d’accès ou de rafraîchissement). Toute l’autorisation est révoquée ; un jeton inconnu est accepté sans erreur.
  • La personne révoque dans Paramètres du profil › Agents connectés (administration) ou Paramètres › Agents connectés (application apprenant).
  • L’organisation révoque un client qu’elle a créé, ou désactive le module API et intégrations, ce qui révoque aussi les connexions des agents apprenants.

Quotas

Point d’accèsLimiteRéponse
/mcp/learning60 appels par minute et par utilisateur429 {"error":"rate_limit"}, Retry-After: 60
/mcp/authoring120 appels par minute et par utilisateur429 {"error":"rate_limit"}, Retry-After: 60
/oauth/authorize100 requêtes par 15 minutes429, en-têtes RateLimit-*
/oauth/token, /oauth/revoke50 requêtes par 15 minutes429, en-têtes RateLimit-*
/oauth/register20 requêtes par heure429, en-têtes RateLimit-*

Outils du serveur apprenant

Tous en lecture seule, idempotents, avec le scope learning:read. Le serveur ne publie ni ressource ni prompt.

OutilEntréesRésultat
inteach_learning_trainings_searchquery? (200 caractères), status? : inProgress, standBy, incoming, allFormations : identifiant de session, nom, statut, verrou, date de début, progression, points, lien
inteach_learning_training_getsessionIdRésumé, chapitres, cours et activités, avec leurs verrous et leur état
inteach_learning_training_start_linksessionIdLien d’ouverture de la formation dans l’application apprenant

Une session inconnue ou appartenant à quelqu’un d’autre renvoie NOT_FOUND.

Outils du serveur d’édition

Les noms ne contiennent que des lettres, des chiffres et des soulignés, format accepté par Microsoft 365 Copilot ; les anciens noms à points (inteach.content.search) ne sont plus reconnus. Tous exigent content:read ; les outils d’écriture exigent aussi content:write et sont masqués sans lui. Pour une autorisation couvrant plusieurs organisations, organizationId est obligatoire.

FamilleOutilsAccès
Contexteinteach_context, inteach_organizations_listLecture
Recherche et lectureinteach_content_search, inteach_content_get, inteach_planning_getLecture
Créationinteach_training_create, inteach_training_duplicate, inteach_course_create, inteach_course_duplicate, inteach_chapter_create, inteach_module_create, inteach_activity_create, inteach_card_createÉcriture
Modificationinteach_content_update, inteach_card_update, inteach_content_reorder, inteach_course_publishÉcriture
Planninginteach_planning_create, inteach_planning_updateÉcriture
Médiasinteach_media_search, inteach_media_get, inteach_media_upload_status ; inteach_media_upload_prepare, inteach_media_upload_sign, inteach_media_upload_complete, inteach_media_upload_cancel, inteach_media_attachLecture ; écriture
Suppressioninteach_content_delete_prepare, inteach_content_delete_status ; inteach_content_delete_confirmÉcriture ; content:delete

Règles communes des outils d’écriture :

  • idempotencyKey obligatoire (8 à 128 caractères A-Z a-z 0-9 _ . : -) : rejouer la même clé ne crée rien de plus ;
  • expectedVersion protège une modification contre une écriture concurrente (CONFLICT) ;
  • un média se téléverse en plusieurs parties, 500 Mio au plus ;
  • dans une organisation en espace Essentiel, inteach_course_create et inteach_course_duplicate sont masqués.

Les erreurs d’outil sont rendues avec isError et un code : INVALID_INPUT, FORBIDDEN, NOT_FOUND, CONFLICT, IDEMPOTENCY_CONFLICT, ORGANIZATION_REQUIRED, UPLOAD_EXPIRED, UPLOAD_LIMIT, RESULT_TOO_LARGE (plus de 2 Mo), INTERNAL_ERROR.

Un client qui annonce l’extension MCP Apps (io.modelcontextprotocol/ui) reçoit en plus l’outil inteach_ui_open et une interface d’édition intégrée.

Exemples de configuration

Client MCP générique

{
  "mcpServers": {
    "inteach-formations": {
      "type": "http",
      "url": "https://api.example.com/mcp/learning"
    }
  }
}

Le client découvre l’autorisation, s’enregistre par DCR, ouvre le navigateur pour le consentement et gère les jetons. Remplacez learning par authoring pour le serveur d’édition.

Claude et ChatGPT

Ajoutez un connecteur personnalisé (« connecteur distant » ou « application MCP » selon le produit) avec l’adresse du serveur. L’enregistrement dynamique et la découverte font le reste : vous arrivez sur la page de consentement InTeach, puis de retour dans l’assistant.

Microsoft 365 Copilot

  1. Créez un client Agent IA des apprenants dans InTeach et cliquez sur Ajouter l’adresse de retour de Microsoft 365 Copilot (https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect).
  2. Dans Microsoft 365 Agents Toolkit ou le portail des développeurs Teams, ajoutez une action MCP avec l’authentification OAuth : identifiant, secret, https://api.example.com/oauth/authorize, https://api.example.com/oauth/token, scope learning:read, PKCE activé.
  3. Avec l’enregistrement dynamique (oauth-dynamic), aucun client n’est à créer : Microsoft exige un secret, qu’InTeach délivre.

Copilot Studio

Champ Copilot StudioValeur
Adresse du serveurhttps://api.example.com/mcp/learning
URL d’autorisationhttps://api.example.com/oauth/authorize
URL du jeton et de rafraîchissementhttps://api.example.com/oauth/token
Scopeslearning:read
Identifiant et secretCeux du client InTeach (mode manuel)

En mode manuel, copiez l’URL de rappel générée par Copilot Studio (https://global.consent.azure-apim.net/redirect/…) dans les URI de redirection du client InTeach. En découverte dynamique, envoyez resource ou demandez à votre interlocuteur InTeach quel serveur est la ressource par défaut de votre environnement.

Dépannage

SymptômeCauseSolution
401 invalid_token à chaque appelJeton expiré, révoqué, ou émis pour une autre ressourceRafraîchissez ; vérifiez resource
403 insufficient_scope sur un outilLe consentement n’a pas accordé content:writeRévoquez puis reconnectez en cochant la modification
invalid_request « The resource parameter must identify a resource of this client »Ressource absente ou ambiguëEnvoyez resource avec l’adresse exacte du serveur
invalid_request à /oauth/authorizePKCE absent ou code_challenge invalideActivez PKCE S256 dans le client
invalid_grant « Code binding mismatch »redirect_uri, resource ou code_verifier différent entre l’autorisation et le jetonRenvoyez les mêmes valeurs
invalid_grant au rafraîchissementJeton déjà utilisé, autorisation expirée après 30 jours, compte ou organisation plus autoriséRelancez l’autorisation
invalid_scopecontent:delete sans content:write, ou scope hors du clientCorrigez les scopes demandés
invalid_clientSecret absent pour un client confidentiel, ou envoyé par un client publicAlignez token_endpoint_auth_method
MODULE_UNAVAILABLELe module API et intégrations n’est pas actifFaites-le activer
403 origin_not_allowedAppel depuis un navigateur d’origine non autoriséeAppelez depuis un serveur, ou faites autoriser l’origine
429 rate_limitQuota par utilisateur dépasséAttendez Retry-After
Copilot Studio, mode manuel, échec à l’autorisationLe mode manuel de Copilot Studio peut ne pas envoyer PKCE, obligatoire chez InTeach (point non vérifié sur un tenant réel)Utilisez la découverte dynamique