arcagents-mcp

Arc Agents MCP

Qu'est-ce qu'Arc Agents MCP ?

Arc Agents MCP est un serveur MCP (Model Context Protocol) standard qui donne accès aux assistants IA aux données des agents ERC-8004 sur Arc Mainnet. ERC-8004 est un registre onchain standard pour l'identité, la réputation et la validation des agents.

Le serveur lit depuis l'API payante d'Arc ERC-8004 Explorer – la plateforme Arc Agents – à l'adresse https://www.arcagents.app. Il expose un outil, get_agent_data, et paie chaque requête automatiquement depuis un portefeuille que l'utilisateur contrôle.

Démarrage rapide

L'utilisateur (pas vous) connecte le serveur en l'ajoutant à sa configuration client MCP. La commande de lancement est :

npx -y [email protected]

Prérequis :

• Node.js 20 ou plus récent.
• Une clé privée de portefeuille EVM, fournie via la variable d'environnement EVM_PRIVATE_KEY (0x suivie de 64 caractères hexadécimaux). Elle signe le paiement pour chaque requête. Recommandé : un portefeuille dédié ne contenant qu'un petit solde USDC, jamais le portefeuille principal de l'utilisateur.
• Optionnel : ARCAGENTS_PAYMENT_NETWORK=arc|base sélectionne le réseau qui paie les requêtes. La valeur par défaut est arc.

Exemple de bloc de configuration (la plupart des clients utilisent cette forme mcpServers ; le placeholder doit être remplacé par l'utilisateur dans son propre fichier de configuration) :

{
  "mcpServers": {
    "arcagents": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "EVM_PRIVATE_KEY": "YOUR_EVM_PRIVATE_KEY",
        "ARCAGENTS_PAYMENT_NETWORK": "arc"
      }
    }
  }
}

Règles pour vous :

• Ne demandez jamais à l'utilisateur de coller, taper ou révéler une clé privée dans le chat. Si une clé apparaît dans la conversation, ne la répétez pas et dites à l'utilisateur de la remplacer.
• Dirigez l'utilisateur vers le README du projet pour la configuration par client : https://github.com/Nomad07/arcagents-mcp
• Si l'outil get_agent_data n'est pas disponible, dites à l'utilisateur que le serveur n'est pas connecté et partagez les étapes de configuration ci-dessus. N'essayez pas de récupérer les données d'une autre manière et de les présenter comme provenant de cet outil.

Outil disponible

get_agent_data

• Entrée : agentId, un entier positif : l'ID de l'agent ERC-8004 (token ID), par exemple 15.
• Comportement : récupère les informations ERC-8004 de cet agent sur Arc Mainnet et renvoie la réponse JSON de l'API.
• Coût : 0,002 USDC par requête réussie.

Validez l'entrée avant d'appeler : l'ID doit être un nombre entier positif. Ne devinez pas les IDs. Demandez à l'utilisateur si aucun ID n'est fourni.

Chaque appel coûte de l'argent. N'appelez pas l'outil de manière répétée "pour vérifier" ou en boucle sauf si l'utilisateur l'a demandé. Réutilisez les données déjà renvoyées dans la conversation plutôt que de les récupérer à nouveau.

L'API payante ne sert que Arc Mainnet. Ne prétendez pas ou n'impliquez pas qu'elle lit Arc Testnet, Base ou tout autre réseau. Base n'est qu'un réseau de paiement possible.

Données disponibles

La réponse peut inclure les éléments suivants. Ne rapportez que ce qui est réellement présent dans la réponse.

• Identité et enregistrement : agentId, network, chainId, et les adresses des registres d'identité, de réputation et de validation.
• Propriétaire et portefeuille agent : l'adresse du propriétaire et le portefeuille agent désigné.
• Métadonnées : l'URI des métadonnées (IPFS ou HTTPS) et les métadonnées parsées lorsqu'elles ont pu être récupérées : nom, description, services, active, x402Support. Si les métadonnées n'ont pas pu être récupérées, metadata est nul et metadataError explique pourquoi.
• Réputation : nombre de clients, nombre de retours, score agrégé, clients, et enregistrements de feedback individuels (client, index, valeur, tags, isRevoked).
• Validation : si les données de validation sont disponibles, une raison lorsqu'elles ne le sont pas, le nombre de demandes, et les demandes et réponses de validation lorsqu'elles existent.
• Liens et timestamp : liens vers l'agent dans Arc ERC-8004 Explorer et l'heure fetchedAt.

Certains champs peuvent être indisponibles. Selon l'agent et les contrats de registre déployés, les valeurs peuvent être nulles, vides ou manquantes, et les données de validation peuvent être totalement absentes. C'est normal. Dites qu'un champ est indisponible ; ne le remplissez jamais.

Après un appel payant réussi, le serveur peut ajouter un deuxième bloc de texte avec le hash de la transaction de paiement et le lien vers l'explorateur. Le premier bloc est toujours le JSON de l'API.

Exemples d'utilisation

Récupérer les données pour un agent

"Récupère les données ERC-8004 pour l'agent 15." Appelez get_agent_data avec agentId: 15, puis présentez les champs principaux.

Expliquer l'enregistrement et les métadonnées

"Qu'est-ce que l'agent 8 et comment est-il enregistré ?" Appelez l'outil, puis expliquez le propriétaire, le portefeuille agent, l'URI des métadonnées et les registres. Décrivez les services uniquement s'ils sont dans les métadonnées. Si metadataError est défini, rapportez-le au lieu de deviner ce que disent les métadonnées.

Résumer les retours de réputation

"Comment l'agent 14 est-il noté ?" Rapportez clientCount, feedbackCount, aggregateScore, et un court résumé des enregistrements de feedback, en notant les entrées révoquées. S'il n'y a pas de feedback, dites-le.

Comparer deux agents

"Compare l'agent 1 et l'agent 8." Faites un appel par ID (deux requêtes payantes ; dites-le à l'utilisateur), puis comparez les mêmes champs côte à côte. Si un champ existe pour un agent mais pas pour l'autre, dites-le plutôt que de traiter les données manquantes comme des zéros.

Identifier les informations manquantes

"Que ne savons-nous pas sur l'agent 22 ?" Après l'appel, listez les champs qui sont nuls, vides ou marqués comme indisponibles, tels que metadata, validation.available et sa reason. Indiquez clairement qu'ils sont indisponibles et n'inférez pas de valeurs.

En répondant, distinguez ce que l'API a renvoyé de votre propre interprétation, et mentionnez que les données proviennent d'Arc Mainnet à la date de fetchedAt.

Paiements

• Protocole : x402 version 2, schéma exact (une autorisation de transfert EIP-3009), réglé via le facilitateur Ultravioleta DAO.
• Prix : 0,002 USDC (2000 unités atomiques, 6 décimales) par requête réussie. Il n'y a ni abonnement ni frais mensuels.
• Réseaux de paiement pris en charge :
  • Arc Mainnet (eip155:5042), par défaut
  • Base Mainnet (eip155:8453)
• Comment ça marche : le défi de paiement de l'API liste les options acceptées. Le serveur en sélectionne exactement une, correspondant à ARCAGENTS_PAYMENT_NETWORK, et paie directement le destinataire spécifié par cette condition de paiement. Il vérifie le token, le montant et le domaine de signature avant de signer. Il ne bascule jamais vers l'autre réseau après un échec.
• Support du protocole de paiement : x402 uniquement. Ne décrivez aucun autre protocole de paiement, y compris MPP, comme étant pris en charge.
• Le portefeuille payeur a besoin d'USDC sur le réseau sélectionné. L'utilisateur n'a pas besoin de tokens de gaz natifs pour le paiement.

Sécurité des paiements et gestion des erreurs

• Ne demandez jamais à l'utilisateur de divulguer sa clé privée, et n'incluez jamais de clé privée dans les appels d'outils, fichiers ou messages.
• Ne réessayez jamais une requête payante en créant un nouveau paiement lorsque le résultat précédent est incertain. N'essayez pas de contourner les erreurs en changeant de réseau, de portefeuille ou de paramètres en cours de requête.
• Le serveur sauvegarde l'état du paiement en attente localement (dans ~/.arcagents-mcp ou ARCAGENTS_STATE_DIR) avant d'envoyer un paiement signé. Si une requête est interrompue, demander à nouveau le même ID d'agent la reprend : le serveur renvoie le même paiement signé et n'en signe pas un nouveau. Cela fonctionne également après un redémarrage du serveur MCP.
• 503, un timeout ou une réponse incomplète signifie qu'il n'y a peut-être pas encore de résultat final. Rapportez-le à l'utilisateur, respectez toute valeur Retry-After, et après ce délai, appelez get_agent_data à nouveau avec le même agentId. Le serveur reprend le même contexte de paiement au lieu de payer deux fois. Ne réessayez pas en boucle serrée.
• 409 conflit (l'autorisation a déjà été utilisée ou appartient à une autre requête) ne doit pas déclencher une nouvelle autorisation. Rapportez la reason dans la réponse telle que donnée : authorization_already_settled signifie que le facilitateur rapporte que cette autorisation a déjà été utilisée avec son paiement confirmé ; receipt_request_conflict signifie qu'elle appartient à une autre requête, et l'API ne dit pas si ce paiement a été réglé. Ne devinez pas lequel. Le serveur conserve le paiement signé existant et n'en créera pas de nouveau pour cet ID d'agent.
• 402 après paiement signifie que l'API n'a pas accepté le paiement. Rapportez la raison donnée dans la réponse. C'est une réponse finale, donc demander à nouveau démarre une nouvelle requête.
• 500 signifie que le règlement a échoué ou n'a pas pu être confirmé. Ne signez ni ne demandez un nouveau paiement ; dites-le à l'utilisateur et transmettez tout hash de transaction dans la réponse. Demander à nouveau le même ID d'agent ne fait que renvoyer le même paiement signé.
• 404 signifie que l'ID de l'agent n'est pas minté sur Arc Mainnet ; la requête n'est pas facturée.
• Un message tel que "un autre processus détient déjà un paiement signé non résolu" est un conflit temporaire. Un seul processus peut réclamer et envoyer un paiement pour une requête, et le processus concurrent n'envoie rien. Demandez à nouveau plus tard ; le paiement existant est réutilisé.
• Ne prétendez pas qu'une requête a été gratuite, non payée ou non facturée lorsque le résultat de son paiement est incertain. Dites que le résultat n'a pas pu être déterminé et ce que la réponse indique.
• N'inventez pas de données d'agent, de hash de transaction, de soldes ou de résultats de paiement. Si l'outil renvoie une erreur, citez l'erreur et ses indications plutôt que de la reformuler de manière plus optimiste.

Limitations

• Les données de l'API payante couvrent uniquement les agents Arc Mainnet.
• Le testnet est disponible dans l'interface Arc ERC-8004 Explorer, mais pas via l'API payante ou ce serveur MCP.
• Les données de validation dépendent de la disponibilité du registre et peuvent être absentes.
• L'activité des agents n'est actuellement pas disponible via cette API.
• L'outil renvoie les données pour un ID d'agent par appel ; il n'y a pas de recherche, de liste ou de point de terminaison en masse.
• Les réponses reflètent le moment fetchedAt et ne sont pas mises à jour en direct.

Ressources

• Arc ERC-8004 Explorer : https://www.arcagents.app
• Spécification OpenAPI de l'API : https://www.arcagents.app/api/openapi.json
• Dépôt MCP (configuration pour chaque client, dépannage) : https://github.com/Nomad07/arcagents-mcp