Intégration MCP

Anyy connecte des commandes locales stdio et des serveurs MCP HTTP distants avec un profil et sa configuration de projet. Chaque serveur possède activation, connexion et exposition d’outils propres. L’ajout enregistre par défaut une configuration activée à connexion différée ; il ne teste pas et ne demande pas de liste d’outils. Utilisez --disable pour l’enregistrer désactivée.

Prérequis de connexion

Les transports clients compatibles sont stdio et Streamable HTTP (http). Un transport sse distinct est rejeté ; HTTP peut néanmoins transporter des flux d’événements dans Streamable HTTP. Les points d’accès distants exigent HTTPS, sauf HTTP en boucle locale.

Pour stdio, installez l’exécutable serveur et ses dépendances sur la machine Anyy. Une commande npx y exige Node.js/npm ; Anyy ne fournit ni ces environnements ni l’installation du serveur. Seul un environnement de processus limité, dont PATH et HOME, est hérité ; définissez explicitement les autres valeurs dans env. Les serveurs HTTP n’exigent pas Node.js local.

Configuration du profil et du projet

Les définitions globales résident dans config.yaml du profil sous mcp.client.servers. Le fichier projet est .anyy/mcp.json dans le Workspace canonique du profil, actuellement <ProfileHome>/workspace/.anyy/mcp.json. Changer de conversation ou de répertoire de travail de session ne choisit pas un autre fichier projet.

Le fichier projet utilise un objet mcpServers :

{
  "mcpServers": {
    "context": {"enabled": false, "exposure": "deferred"},
    "project-docs": {"url": "https://mcp.example.com", "exposure": "codemode"}
  }
}

Une définition complète de projet remplace celle de même nom du profil. Une entrée sans command, url ni type est un remplacement partiel : elle exige un serveur du profil de même nom et n’accepte que enabled, exposure et toolExposure. Chaque valeur fournie remplace sa valeur héritée ; toolExposure remplace l’objet ordonné complet. Les autres champs, authentification comprise, viennent toujours du profil. Une définition complète de projet ne peut pas définir de référence fournisseur auth.

Utilisez anyy mcp show SERVER_ID pour inspecter la source sélectionnée et son remplacement éventuel. Une configuration projet mal formée apparaît dans les diagnostics au lieu de devenir silencieusement une autre définition.

Ajouter ou supprimer une définition de projet

anyy mcp add project-docs --local --url https://mcp.example.com
anyy mcp remove project-docs --local

--local (ou -l) écrit uniquement dans le fichier projet de ce profil. L’ajout remplace l’entrée de même nom sans --force ; la suppression ne retire que cette entrée, préserve définitions de profil et autorisations enregistrées et signale une erreur si l’entrée manque. Ces modifications ne reconnectent pas un serveur actif. Le démarrage ou session.reload à l’état inactif charge la nouvelle définition ; supprimer un remplacement révèle celle du profil. Sans --local, ajout/suppression gardent le comportement ordinaire du profil.

Valeurs et chemins

Les actions ordinaires add/configure/set et enregistrements Dashboard gardent la chaîne saisie, même pour un nom sensible d’environnement/en-tête ou un secret client OAuth. Elles ne la transforment pas automatiquement en référence Secret. Utilisez secret: explicite pour un secret Anyy existant ; les chaînes ordinaires conservent les expressions ci-dessous.

Seules les valeurs d’environnement stdio, d’en-têtes HTTP et clientSecret OAuth utilisent des expressions. $VAR et ${VAR} lisent l’environnement du processus Anyy ; $$ produit un $ littéral et $! un ! littéral. Une valeur commençant par ! exécute une commande shell locale et utilise sa sortie sans espaces de bord. L’évaluation est unique : une valeur développée n’est pas réévaluée. Les commandes partent du répertoire du processus Anyy avec un délai de 10 secondes et une sortie limitée à 1 Mio.

Dans les définitions de profil, les préfixes exacts env:, secret: ou file: passent d’abord par le résolveur d’identifiants existant ; son résultat est final. Dans une définition complète de projet, ces préfixes sont littéraux. Un remplacement partiel hérite de l’interprétation du profil. Les URL et autres champs OAuth, tels que clientId, scope et callbackUrl, n’utilisent pas ces expressions.

Les chemins de commande et d’arguments développent un ~ initial ; cwd accepte aussi un chemin relatif au répertoire personnel ou au Workspace. Ils n’exécutent pas d’expressions $ ou !. Le répertoire stdio est distinct de la racine Workspace annoncée et du répertoire de processus utilisé par !command.

Ajouter un serveur local

anyy mcp add context \
  --transport stdio \
  --command npx \
  --exposure codemode \
  --args -y @upstash/context7-mcp

Placez les options Anyy avant --args ou -- ; les arguments restants vont au serveur. --cwd DIR facultatif concerne stdio et accepte les mêmes chemins absolus, relatifs au Workspace ou avec préfixe personnel que cwd enregistré ; le chemin saisi n’est pas rogné. Répétez --env KEY=VALUE au besoin avec références de secrets pour les valeurs sensibles. Un serveur local s’exécute avec les accès système d’Anyy.

Ajouter un serveur distant

anyy mcp add remote-docs --url https://mcp.example.com
anyy mcp add provider-docs --url https://mcp.example.com --auth '{"provider":"provider-id"}'
anyy mcp add header-docs --url https://mcp.example.com --header Authorization=secret:mcp/header-docs/token

HTTP prend en charge OAuth automatique sans référence fournisseur ni en-tête Authorization. Un serveur anonyme peut se connecter sans connexion utilisateur ; l’absence initiale de jeton ne signifie pas à elle seule une réauthentification nécessaire. auth est un objet JSON fournisseur ; oauth, un objet typé d’options distinct. Passez par exemple --oauth '{"clientId":"registered-client"}' pour une inscription existante. Les anciens sélecteurs chaînes oauth, header et none sont rejetés.

Enregistrez le serveur avant de lancer la connexion :

anyy mcp login remote-docs

Si le serveur rejette les identifiants client OAuth enregistrés, Anyy peut effacer l’autorisation locale rejetée et tenter une récupération une fois ; il peut demander une nouvelle connexion. Aucun appel d’outil n’est rejoué. L’absence de vérificateur d’échange de code termine la tentative.

Rappel navigateur et redirection manuelle

Lancez anyy mcp login remote-docs --timeout 300 ou sélectionnez Sign in sur le serveur enregistré dans Dashboard ou Tools & MCP dans la configuration TUI. Terminez l’autorisation dans votre navigateur. Si celui-ci ne peut joindre la machine Anyy, collez l’URL complète de redirection de sa barre d’adresse dans le champ de cette connexion. Gardez l’URL privée.

Le délai CLI est de 300 secondes par défaut et couvre seulement l’autorisation, pas les contrôles de connexion ni la reconnexion ultérieure. Il vérifie d’abord la connexion : si elle est prête, il indique Already signed in ; une erreur ordinaire ne lance pas la connexion utilisateur. Une connexion CLI explicite peut authentifier un serveur enregistré désactivé sans activer ses outils. En terminal non interactif, la CLI attend seulement le rappel navigateur et ne lit pas d’URL collée.

La TUI utilise Ctrl+Y pour copier le lien complet d’autorisation et Esc pour annuler. Fermer la connexion Dashboard ou quitter la page annule la tentative en attente. La fin efface le lien temporaire et le champ.

Si un appel exige une autorisation OAuth interactive ou des portées supplémentaires, la connexion indique qu’une connexion utilisateur est requise. Lancez-la explicitement depuis CLI, Dashboard ou TUI. L’appel échoué n’est ni actualisé ni rejoué automatiquement. Annuler termine cette tentative avec le résultat dédié d’annulation, sans continuer en arrière-plan.

Connexion depuis un autre processus

Si un autre processus enregistre des identifiants pour le même profil/serveur, une connexion en attente d’authentification les vérifie au début d’un tour modèle. Une requête déjà préparée conserve ses déclarations ; les outils nouvellement découverts apparaissent à la préparation d’une requête ultérieure. Anyy ne surveille pas les identifiants en arrière-plan. Une configuration modifiée à la main exige toujours un démarrage ou rechargement des ressources d’une session inactive ; changer les identifiants ne redémarre pas une connexion ordinairement échouée ou fermée par ce mécanisme.

Déconnexion

anyy mcp logout remote-docs

Utilisez l’ID exact du serveur configuré. Cela retire l’entrée locale actuelle d’identifiants et ferme la connexion, mais garde configuration, outils/ressources/instructions en cache. Sans entrée, l’opération réussit sans effet. Elle ne révoque pas les jetons distants ; un ancien recours reconnu peut nécessiter une autre déconnexion. La commande utilise le profil résident s’il est disponible ; un délai ou une réponse résidente échouée n’autorise pas une modification hors ligne.

MCP ne sonde pas périodiquement le catalogue d’outils. La découverte/actualisation a lieu à la connexion, lors d’opérations explicites et de vraies notifications de changement ; la connexion de notification et la récupération de session compatible restent présentes.

Le paramètre par serveur connect_timeout_ms est retiré ; supprimez-le des anciennes configurations. call_timeout_ms s’applique séparément à l’initialisation, à la découverte et aux requêtes d’outils ; l’ouverture n’a aucun délai total supplémentaire. Les échecs HTTP initiaux admissibles peuvent être réessayés deux fois avant une erreur finale.

Flux HTTP et renouvellement de jetons

Après initialisation, le transport HTTP par défaut ouvre un flux GET distinct pour requêtes et notifications serveur. L’authentification par fournisseur obtient le jeton actuel à chaque envoi HTTP réel, GET compris ; elle n’enregistre pas de copie MCP supplémentaire du jeton fournisseur. Ce comportement n’ajoute aucun réglage Dashboard ou profil.

Le client HTTP préserve les en-têtes configurés sans ajouter d’Origin localhost aux serveurs en boucle locale. Un Origin explicitement configuré n’est pas remplacé. Les serveurs appliquent toujours leur validation Origin.

Anyy peut reprendre un flux interrompu si le serveur a fourni un curseur. Il poursuit par GET avec le dernier ID d’événement sans renvoyer l’appel d’outil. Sans curseur, un flux de réponse terminé avant sa réponse fait échouer la requête. Fermer la connexion arrête la récupération.

Les processus partageant les identifiants du profil/serveur coordonnent aussi le renouvellement et relisent le jeton enregistré avant une autre demande. Cette coordination ne garantit pas la récupération de tout crash ou perte de bail.

Initialisation et racines Workspace

Le résultat d’initialisation doit fournir une chaîne protocolVersion, un objet capabilities et serverInfo avec chaînes name et version. instructions facultatif doit être une chaîne. Un résultat invalide ferme la connexion sans déclarer le serveur connecté. Instructions absentes, vides ou avec espaces de bord restent distinctes ; leur affichage en résumé supprime les espaces de bord.

Les serveurs demandant roots/list reçoivent le répertoire canonique du Workspace résident comme unique racine fichier. Elle est figée à la création du gestionnaire MCP ; changer de conversation ou de Workspace logique ne redirige pas la connexion partagée.

Un processus stdio local utilise ce répertoire par défaut. Son cwd peut être absolu, relatif à celui-ci ou utiliser le préfixe personnel ; chemins de commande et arguments acceptent aussi ce préfixe. Les espaces de cwd sont préservés. Changer cwd ne change pas la racine annoncée. Celle-ci fournit le contexte sans être une limite d’autorisation des fichiers.

Exposition et découverte d’outils

Exposition	Utilisation
codemode	Par défaut ; découverte et appel par Codemode
deferred	Découverte par recherche d’outils
direct	Déclaration directe au modèle
hidden	Indisponible à la découverte modèle et Codemode

L’objet ordonné toolExposure remplace le défaut du serveur. Les noms exacts priment ; sinon, le premier joker correspondant gagne. Configurez sans demande de découverte :

anyy mcp configure context --exposure deferred
anyy mcp set context description 'Documentation tools'
anyy mcp set context toolExposure '{"get-*":"deferred","*":"hidden"}'

Activation et exposition sont enregistrées dans le fichier de définition sélectionné ou son remplacement projet existant. Changer l’exposition met à jour les déclarations disponibles sans reconnexion ; activer/désactiver ne touche que ce serveur. Si la connexion échoue après l’enregistrement, inspectez son état ; le paramètre reste enregistré.

Pour un serveur de profil sans remplacement projet, utilisez anyy mcp disable SERVER_ID --project ou enable SERVER_ID --project pour enregistrer seulement son activation dans le fichier projet. Cette option ne concerne ni les définitions complètes de projet ni les serveurs déjà remplacés ; l’activation ordinaire utilise leur source sélectionnée.

configure --description et --tool-exposure, ainsi que set/unset génériques, modifient la définition brute du profil. Ne les combinez pas avec configure --exposure ou --enable ; lancez des commandes séparées. Pour changer un toolExposure de projet, modifiez cette entrée plutôt qu’une définition de profil masquée.

Ces champs suivent la configuration MCP Pi v1.2 figée et son enregistrement. Le RPC tool_exposure d’Anyy est une chaîne JSON préservant l’ordre des règles à travers la frontière de map RPC ; la configuration enregistrée contient une valeur toolExposure ordonnée.

Les outils MCP ne génèrent ni n’activent d’ensembles personnels mcp-*. Ensembles ordinaires, rôles et restrictions de noms d’outils imposées par la session parente restent distincts. Les anciens mcp.client.enabled, tools.include, tools.exclude, tools.trusted, --include, --exclude, --activate-toolset et la demande de sélection sont retirés. Supprimez ces champs : ils sont rejetés, pas ignorés.

Résumés de serveurs dans la demande

Anyy ajoute une section mcp_servers au début d’une exécution. Elle liste les serveurs activés configurés pour Codemode ou la découverte différée, y compris en cours de connexion. Les serveurs uniquement directs, uniquement cachés et désactivés sont omis ; un serveur mixte porte le libellé Codemode si les deux découvertes sont configurées. La liste aide à découvrir, sans attester une connexion réussie.

Votre description configurée prime. Sinon le résumé utilise la première ligne d’instructions disponibles du serveur. Les noms sont triés, les résumés raccourcis et la liste bornée compte les serveurs omis. Gardez les descriptions concises et sans identifiants.

Cette section reste figée pendant les tours d’outils suivants de l’exécution. Description, configuration ou instructions nouvellement disponibles apparaissent à la demande suivante. Si aucun serveur n’est admissible, la section est retirée.

Inspecter et appeler des outils

anyy mcp show context
anyy mcp probe context
anyy mcp test context
anyy mcp list
anyy mcp status --json
anyy mcp logs context
anyy mcp reload context
# If the inspected server advertises a search tool with a query field:
anyy mcp call docs.search --args '{"query":"Anyy"}'

L’appel ci-dessus est illustratif : utilisez le nom serveur d’origine et les arguments exacts de show/probe. Les noms MCP visibles du modèle sont qualifiés et peuvent être normalisés ou suffixés en cas de collision ; la découverte Codemode retourne les identifiants JavaScript. Utilisez la déclaration active sans fabriquer de nom. Consultez Découverte Codemode et Recherche d’outils.

anyy mcp reload reconnecte avec la configuration déjà chargée sans relire les fichiers modifiés. Le démarrage et le RPC session.reload d’une session inactive relisent profil et projet. Aucun observateur de fichiers MCP distinct n’existe. Consultez Application des changements.

La sonde est facultative et ne conditionne ni sauvegarde ni activation. Son inventaire unique tools contient name, visible_name, description, exposure et offered. Un outil offert est annoncé actuellement par le serveur, sans résultat d’approbation. Un appel préparé résout serveur et offre actuels lors de son exécution.

Les nouveaux appels directs sont validés contre le JSON Schema actuel. Un appel préparé avant remplacement de configuration conserve son schéma déclaré et ses arguments validés, puis résout le serveur actuel à l’exécution. Le remplacement ferme les anciennes connexions en cours sans rejouer leurs appels sur le nouveau serveur. Les outils sélectionnés et anyy mcp call s’exécutent directement, écritures comprises. Propriété du profil, authentification, protection des identifiants et restrictions ordinaires des noms s’appliquent toujours. Les anciennes clés de règles d’approbation/exécution restent rejetées.

Ressources et modèles

Anyy fournit trois outils partagés de ressources :

Outil	Entrée	Résultat programmatique
list_mcp_resources	server, cursor facultatifs	resources, server facultatif, nextCursor, errors
list_mcp_resource_templates	server, cursor facultatifs	resourceTemplates, server facultatif, nextCursor, errors
read_mcp_resource	server, uri obligatoires	{server, uri, contents}

Précisez un serveur pour lister une page, puis passez nextCursor pour la suivante. Omettez-le pour collecter toutes les pages des serveurs admissibles ; un curseur exige un serveur. Les listes combinées conservent les réussites et nomment les échecs dans errors. Un échec du serveur sélectionné rejette l’appel.

La disponibilité suit les serveurs activés déclarant la capacité de ressources avec une exposition non cachée. Les outils partagés utilisent l’exposition admissible la plus large : direct, puis codemode, puis deferred. Ils apparaissent une fois la capacité connue ; son retrait masque les définitions enregistrées auparavant. Les inventaires sont récupérés à l’appel, pas au démarrage.

La lecture conserve le JSON programmatique complet. La sortie modèle utilise texte, images ou références de fichiers enregistrés ; le texte long suit la limite partagée de 20 Kio. Les ressources d’interface MCP App sont omises. Un échec de livraison ne répète pas une lecture réussie.

Les anciens noms de ressources/prompts par serveur et commutateurs tools.resources/tools.prompts sont retirés. Supprimez-les : leur présence est rejetée, même avec false ou null. L’état conserve resources_advertised, prompts_advertised et server_capabilities, et retire les anciens champs d’activation/posture/compte. Les méthodes brutes de prompts du SDK restent des API de protocole, sans outils générés pour l’agent.

Connecter un autre client MCP à Anyy

anyy mcp serve expose par stdio les interfaces de conversations, messages et événements de l’assistant résident. Ses outils par défaut sont conversations_list, conversation_get, messages_read, events_poll, events_wait et messages_send.

mcp.server.scopes accepte seulement conversations et messaging. L’omettre inclut les deux ; [] n’expose aucun outil. Les outils de liste/réponse d’approbation ont été retirés. La configuration rejette l’ancien périmètre approvals, les périmètres fictifs non implémentés et les anciennes clés expose_approvals/expose_tools. Les opérations passent toujours par les RPC Gateway existants.

API de résultat de conversation

messages_send accepte uniquement session_id et text :

{"session_id":"ses_example","text":"Summarize my tasks"}

Il admet l’entrée par session.submit, puis appelle execution.await avec le submission_id d’origine. Le contenu texte JSON du résultat contient :

Champ	Signification
submission	Reçu d’admission d’origine, avec son submission_id
execution	État et résultat observés de l’invocation réelle de cette entrée
messages	Messages de résultat ordonnés chargés depuis les références enregistrées de cette invocation
timed_out	Indique si l’observation a expiré avant un résultat

Une demande ultérieure dans la même session ne peut pas remplacer ces messages. messages_read interroge l’historique et n’est pas une source de réponse de secours. Protection et traitement des pièces ordinaires s’appliquent.

Le résultat MCP a isError=false pour une réussite ou une suspension réelle pour clarification. L’état suspended conserve ses identifiants de clarification et signifie qu’une entrée est nécessaire, sans réponse finale. Échec, interruption, entrée effacée, délai ou état non final ont isError=true. Une voie inactive n’est réussie qu’avec outcome=succeeded.

Pour utiliser Gateway RPC directement, préservez les deux ID de l’admission :

{"execution_id":"exec_example","submission_id":"sub_example","timeout_ms":30000}

execution.await retourne {execution, submission_id, timed_out, messages}. L’attente suit l’exécution réservée ou sélectionnée d’origine et sa lignée de récupération, y compris un échec de préparation avant sélection. Une entrée non sélectionnée effacée se résout avec outcome=interrupted, stop_reason=input_cleared et aucun message. L’attente n’active jamais d’entrée en file.

Un délai retourne timed_out=true avec messages vide. Délai ou annulation de l’appelant termine uniquement l’observation ; le travail accepté continue. execution_id seul observe la voie réutilisable sans identifier le résultat d’une demande précise. Inspectez la session avant de soumettre de nouveau une requête expirée.

Désactiver ou supprimer

anyy mcp disable context
anyy mcp remove context

Désactiver conserve la configuration. La suppression ordinaire d’un serveur MCP dans la configuration du profil retire sa définition et ses identifiants gérés par Anyy ; remove --local ne supprime que l’entrée projet et préserve les autorisations. Les ensembles personnels ordinaires sont conservés. Pour les opérations sur une définition de serveur du profil, --force confirme remplacement ou suppression dans les scripts sans contourner propriété ni gestion des identifiants.

Dépannage

Problème	Points à vérifier
Serveur local ne démarrant pas	Commande, arguments, exécutable et environnement
Serveur distant non autorisé	Référence fournisseur, état OAuth ou en-tête protégé
Outil indisponible	Activation, exposition et offre actuelle du serveur
Schéma modifié	Inspectez la définition actuelle et réessayez avec des arguments valides
Ancien contenu de fichiers encore affiché	Relisez par une session inactive ou redémarrez, puis inspectez la source choisie

Consultez MCP dans Dashboard pour les formulaires et l’inspection.

Résultats et pièces jointes

Les résultats programmatiques conservent les valeurs MCP acceptées, dont null, false, nombres, chaînes et tableaux dans structuredContent. S’il existe des blocs de contenu, Anyy les convertit pour le modèle sans ajouter séparément structuredContent. Si le tableau est vide et structuredContent présent, Anyy formate ce JSON en bloc texte modèle. Ce texte passe par la même protection d’identifiants et limite de 20 Kio que les autres textes MCP. Les schémas de sortie affectent le retour déclaré sans transformer les résultats distants en validation locale. Le contenu modèle préserve l’ordre des textes et images. Audio et blocs inconnus utilisent les marqueurs textuels Pi ; les ressources intégrées deviennent texte/images ou fichiers binaires enregistrés. Au-delà de 20 Kio, le texte utilise la sortie complète enregistrée et une projection début/fin.

Un isError distant résolu reste une erreur. Une exception de transport ou JSON-RPC rejette l’appel. La livraison image/fichier utilise le chemin Artifact existant propriétaire de la session, préserve l’ordre et ne répète pas l’appel distant en cas d’échec de livraison. Le texte est protégé avant enregistrement. Les sauvegardes commencent pour tous les blocs avant que la conversion attende leur fin ; un bloc invalide peut donc rejeter la conversion tandis que les sauvegardes commencées se terminent.

Les erreurs réseau ordinaires ne rejouent pas automatiquement les appels ; la récupération de session expirée est distincte. Inscription OAuth, renouvellement des jetons et transport dépendent du service externe. Inspectez connexion réelle et résultat avant de vous y fier.