Odysseus AI MCP : configuration des serveurs, OAuth et depannage

Ce que MCP signifie dans un espace Odysseus

Model Context Protocol (MCP) est un protocole qui permet a une application IA de decouvrir et d'appeler des outils exposes par un serveur. Le serveur peut fournir des documents en lecture, une recherche de calendrier, une fonction de recherche ou une action comme la creation d'une tache. Il definit le schema et le comportement de l'outil ; l'hote decide quand se connecter, quoi afficher et si une personne doit approuver l'appel.

Dans une configuration Odysseus AI MCP, ne traitez pas le modele, l'espace et le processus MCP comme une seule zone de confiance. Un modele local peut tourner sur votre machine tandis qu'un serveur MCP envoie une requete a une API hebergee. Un serveur distant peut etre hors de votre reseau meme si l'interface Odysseus est locale. Notez cette limite avant d'ajouter des identifiants ou des fichiers prives.

Avant la configuration : authentification, admin et limites reseau

La documentation officielle d'Odysseus place la gestion MCP et les tokens API dans la zone administrateur. Connectez-vous avec un compte autorise et verifiez que le deploiement a charge les memes variables que le processus Web. Une session de chat fonctionnelle dans le navigateur ne prouve pas que le processus serveur peut joindre un endpoint MCP.

Conservez l'authentification pendant les tests. Ouvrir temporairement une route admin sans connexion ou exposer un port de modele cree une surface difficile a refermer. Avec Docker, le callback et le nom de service doivent etre joignables depuis le reseau du conteneur, pas seulement depuis le navigateur de l'hote. Verifiez DNS, TLS, pare-feu et origine autorisee.

Examiner les serveurs MCP integres et le cache npx

Odysseus documente des serveurs MCP integres pour commencer rapidement. Une entree integree depend tout de meme de son environnement : la commande doit exister, le processus doit demarrer avec les bons arguments et le serveur doit disposer de son runtime. Un libelle integre est un raccourci d'enregistrement, pas une preuve de sante.

Certains exemples utilisent un paquet npx depuis un cache local. Le premier demarrage peut resoudre un paquet puis les demarrages suivants utiliser la copie en cache. Verifiez le paquet et la version autorises. Sur un hote isole, preparez un cache approuve ou installez la commande localement au lieu de relancer une resolution qui ne peut pas atteindre le registre.

1. Choisir une entree a faible risque

   Preferez une liste de documents ou une ressource de test. Evitez le shell et les chemins de fichiers trop larges.

2. Verifier l'environnement

   Lancez la commande depuis la meme image ou le meme conteneur qu'Odysseus et masquez les secrets dans stderr.

3. Controler npx

   Verifiez la resolution depuis le cache ou le registre autorise et examinez la version.

npx -y @playwright/mcp@latest --help

docker compose logs --tail=120 odysseus

Ajouter un serveur MCP distant avec OAuth

Un serveur distant OAuth ajoute un echange d'identite au transport et au handshake. L'hote Odysseus lance l'autorisation, l'utilisateur accepte les portees, puis le fournisseur renvoie le navigateur vers le callback enregistre. Ce callback doit resoudre vers la base publique connue du fournisseur ; un localhost a l'interieur d'un conteneur ne fonctionne pas pour un navigateur distant.

Le guide de configuration Odysseus documente OAUTH_REDIRECT_BASE_URL pour les serveurs MCP distants OAuth. Definissez-la au niveau du deploiement, gardez le schema et le chemin stables, puis redemarrez le service qui lit les variables. Ne collez jamais un client secret dans une page, un prompt, une capture ou un JSON versionne. Le fournisseur OAuth reste la reference des redirects et scopes.

1. Confirmer le callback

   Notez la route HTTPS exacte et les scopes dans la documentation du serveur.

2. Definir OAUTH_REDIRECT_BASE_URL

   Ajoutez la valeur a l'environnement du deploiement et redemarrez le processus.

3. Autoriser depuis Odysseus

   Lancez le flux dans Odysseus et verifiez le retour vers l'hote et le chemin attendus.

OAUTH_REDIRECT_BASE_URL=https://mcp.example.com/oauth/callback

Suivre une procedure de test repetable

Repetez la meme sequence lorsque vous ajoutez ou modifiez un serveur Odysseus AI MCP : sante de l'espace, processus, handshake, puis un outil avec une entree connue. Cet ordre separe un probleme d'inference, de transport, de permission ou de fournisseur au lieu de les cacher sous une erreur de connexion.

Conservez un resultat concret : nom du serveur et de l'outil, forme des arguments, statut, duree et identifiant de requete sans secret. Retirez tokens, en-tetes, documents prives et prompts complets. En cas d'echec, archivez le schema et un exemple redige, jamais un payload prive.

1. Verifier la sante Odysseus

   Confirmez que le Web et ses dependances fonctionnent avant d'ouvrir la gestion MCP.

2. Verifier le processus

   Comparez commande, transport, variables et endpoint avec les logs.

3. Lister schemas et capacites

   Controlez les noms, arguments obligatoires et operations de lecture ou d'ecriture.

Depanner serveurs injoignables, droits et anciens enregistrements

Commencez par la couche qui a echoue. Si le processus ne demarre pas, verifiez commande, paquet, dossier et environnement. S'il demarre mais n'affiche aucun outil, examinez transport et handshake. Si un outil apparait mais echoue, controlez ses arguments, le scope OAuth, le quota et l'endpoint amont. Un modele qui ignore un outil peut aussi signaler un probleme de boucle ou d'hote.

Le reseau Docker provoque beaucoup de faux problemes MCP. Un nom qui marche dans le navigateur peut ne pas se resoudre dans le conteneur. Testez l'endpoint depuis le meme runtime, controlez les certificats et la sortie reseau, puis utilisez le nom de service ou la passerelle adaptee. Gardez les ports de modele et de service prives par defaut.

Appliquer une checklist pratique pour tokens et reseau

MCP rend les capacites composables ; la configuration la plus sure est donc la plus petite qui suffit. Accordez seulement les dossiers, domaines et actions necessaires. Preferez la lecture, exigez une approbation visible pour les ecritures et prevoyez la rotation des tokens OAuth et API. Un processus local peut toujours transmettre des donnees a un fournisseur externe.

• Utilisez un compte ou espace de test pour la premiere connexion.
• Examinez et verrouillez commandes et versions de paquets.
• Stockez les identifiants dans l'environnement ou un coffre de secrets.
• Limitez dossiers, domaines et outils au strict necessaire.
• Masquez tokens, documents prives et prompts complets dans les logs.