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é.
| Serveur | Adresse | Utilisateurs | Accès |
|---|---|---|---|
| Édition pédagogique | https://api.example.com/mcp/authoring | Administrateurs et gestionnaires | Lecture, écriture ; suppression réservée aux superadministrateurs |
| Mes formations | https://api.example.com/mcp/learning | Apprenants, et tout compte actif membre de l’organisation | Lecture 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
POSTest accepté ; une autre méthode reçoit405avecAllow: POST. - Chaque requête porte
Authorization: Bearer <jeton>. - Un appel venant d’un navigateur avec un en-tête
Originnon autorisé reçoit403 {"error":"origin_not_allowed"}. Les appels de serveur à serveur, sansOrigin, 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"
| Document | Adresse |
|---|---|
| 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 :
| Champ | Valeur |
|---|---|
authorization_endpoint | /oauth/authorize |
token_endpoint | /oauth/token |
registration_endpoint | /oauth/register |
revocation_endpoint | /oauth/revoke |
response_types_supported | code |
grant_types_supported | authorization_code, refresh_token (et client_credentials pour l’API publique) |
token_endpoint_auth_methods_supported | client_secret_basic, client_secret_post, none |
code_challenge_methods_supported | S256 |
authorization_response_iss_parameter_supported | true |
Enregistrer un client
Enregistrement dynamique (DCR)
POST /oauth/register (RFC 7591) accepte trois champs, et ignore les autres :
| Champ | Règle |
|---|---|
redirect_uris | 1 à 10 adresses ; HTTPS, ou HTTP sur localhost, 127.0.0.1 ou [::1] ; ni fragment ni identifiants |
client_name | 120 caractères au plus ; « Agent MCP » par défaut |
token_endpoint_auth_method | client_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 :
- un client d’organisation obtient la ressource de son usage ;
- un client dynamique obtient la ressource dont les scopes couvrent ceux demandés (
openid,profile,emailetoffline_accesssont ignorés) ; - sans scope exploitable, la ressource par défaut de l’environnement s’applique, si elle est définie ;
- 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_deniedavecissetstate.
Scopes
| Scope | Serveur | Effet |
|---|---|---|
learning:read | Apprenant | Lire ses formations, leur description et sa progression |
content:read | Édition | Lire contenus, médias et plannings. Toujours requis |
content:write | Édition | Créer, modifier, réordonner, publier, importer des médias |
content:delete | Édition | Confirmer 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ément | Durée et règles |
|---|---|
| Code d’autorisation | 60 secondes, usage unique. Une réutilisation révoque l’autorisation |
| Jeton d’accès | 15 minutes, opaque, sans dépasser l’échéance de l’autorisation |
| Jeton de rafraîchissement | Tournant à chaque usage. Une réutilisation révoque l’autorisation |
| Autorisation | 30 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ès | Limite | Réponse |
|---|---|---|
/mcp/learning | 60 appels par minute et par utilisateur | 429 {"error":"rate_limit"}, Retry-After: 60 |
/mcp/authoring | 120 appels par minute et par utilisateur | 429 {"error":"rate_limit"}, Retry-After: 60 |
/oauth/authorize | 100 requêtes par 15 minutes | 429, en-têtes RateLimit-* |
/oauth/token, /oauth/revoke | 50 requêtes par 15 minutes | 429, en-têtes RateLimit-* |
/oauth/register | 20 requêtes par heure | 429, 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.
| Outil | Entrées | Résultat |
|---|---|---|
inteach_learning_trainings_search | query? (200 caractères), status? : inProgress, standBy, incoming, all | Formations : identifiant de session, nom, statut, verrou, date de début, progression, points, lien |
inteach_learning_training_get | sessionId | Résumé, chapitres, cours et activités, avec leurs verrous et leur état |
inteach_learning_training_start_link | sessionId | Lien 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.
| Famille | Outils | Accès |
|---|---|---|
| Contexte | inteach_context, inteach_organizations_list | Lecture |
| Recherche et lecture | inteach_content_search, inteach_content_get, inteach_planning_get | Lecture |
| Création | inteach_training_create, inteach_training_duplicate, inteach_course_create, inteach_course_duplicate, inteach_chapter_create, inteach_module_create, inteach_activity_create, inteach_card_create | Écriture |
| Modification | inteach_content_update, inteach_card_update, inteach_content_reorder, inteach_course_publish | Écriture |
| Planning | inteach_planning_create, inteach_planning_update | Écriture |
| Médias | inteach_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_attach | Lecture ; écriture |
| Suppression | inteach_content_delete_prepare, inteach_content_delete_status ; inteach_content_delete_confirm | Écriture ; content:delete |
Règles communes des outils d’écriture :
idempotencyKeyobligatoire (8 à 128 caractèresA-Z a-z 0-9 _ . : -) : rejouer la même clé ne crée rien de plus ;expectedVersionprotè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_createetinteach_course_duplicatesont 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
- 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). - 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, scopelearning:read, PKCE activé. - Avec l’enregistrement dynamique (
oauth-dynamic), aucun client n’est à créer : Microsoft exige un secret, qu’InTeach délivre.
Copilot Studio
| Champ Copilot Studio | Valeur |
|---|---|
| Adresse du serveur | https://api.example.com/mcp/learning |
| URL d’autorisation | https://api.example.com/oauth/authorize |
| URL du jeton et de rafraîchissement | https://api.example.com/oauth/token |
| Scopes | learning:read |
| Identifiant et secret | Ceux 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ôme | Cause | Solution |
|---|---|---|
401 invalid_token à chaque appel | Jeton expiré, révoqué, ou émis pour une autre ressource | Rafraîchissez ; vérifiez resource |
403 insufficient_scope sur un outil | Le consentement n’a pas accordé content:write | Ré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/authorize | PKCE absent ou code_challenge invalide | Activez PKCE S256 dans le client |
invalid_grant « Code binding mismatch » | redirect_uri, resource ou code_verifier différent entre l’autorisation et le jeton | Renvoyez les mêmes valeurs |
invalid_grant au rafraîchissement | Jeton déjà utilisé, autorisation expirée après 30 jours, compte ou organisation plus autorisé | Relancez l’autorisation |
invalid_scope | content:delete sans content:write, ou scope hors du client | Corrigez les scopes demandés |
invalid_client | Secret absent pour un client confidentiel, ou envoyé par un client public | Alignez token_endpoint_auth_method |
MODULE_UNAVAILABLE | Le module API et intégrations n’est pas actif | Faites-le activer |
403 origin_not_allowed | Appel depuis un navigateur d’origine non autorisée | Appelez depuis un serveur, ou faites autoriser l’origine |
429 rate_limit | Quota par utilisateur dépassé | Attendez Retry-After |
| Copilot Studio, mode manuel, échec à l’autorisation | Le 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 |