Agents IA et MCP

N’importe quel agent IA peut utiliser Xaalis : apprendre l’API, ouvrir un compte sandbox, encaisser des paiements Wave et Orange Money, rembourser, facturer des abonnements et payer des personnes — avec peu ou pas d’aide humaine, et sans jamais pouvoir déplacer de l’argent réel au-delà de ce qu’un humain a autorisé.

Vous voulez…	Utilisez
qu’un assistant (Claude, ChatGPT, Cursor, VS Code, Codex…) utilise Xaalis pour vous	le serveur MCP — connectez votre client
qu’un agent de code intègre Xaalis dans votre application	les Agent Skills (ou le plugin Claude Code) + le serveur MCP pour la documentation et les objets de test
que votre propre agent (OpenAI, Anthropic, Vercel AI SDK, LangChain, Python) appelle Xaalis	le catalogue d’outils — frameworks

Documentation lisible par les LLM : /llms.txt · /llms-full.txt.

Déploiement en cours

Le serveur hébergé (https://mcp.xaalis.org/mcp et /sandbox) et la connexion avec votre compte du tableau de bord Xaalis sont en service. Les paquets npm @xaalis/mcp et @xaalis/ai-tools sont en cours de publication : en attendant, utilisez le serveur hébergé.

Ce qu’un agent peut faire — l’identifiant décide

Le serveur MCP ne liste que les outils autorisés par l’identifiant connecté : un modèle ne peut donc pas appeler ce qu’il ne voit pas. C’est la première défense contre une injection de prompt qui lui demanderait de « juste envoyer un versement ». L’API applique ensuite les mêmes limites une seconde fois.

Identifiant	Outils
aucune	xaalis_whoami, xaalis_search_docs, xaalis_sandbox_signup (crée un compte sandbox ; la session l’utilise ensuite)
sk_test_… sandbox	tout, avec de l’argent fictif : paiements + xaalis_simulate_payment, remboursements, abonnements + xaalis_advance_subscription, versements, configuration des portefeuilles d’agent
sk_live_…	tout lire ; créer des paiements et des abonnements (argent entrant) ; annuler des abonnements ; désactiver des portefeuilles d’agent. Aucun versement. Remboursements uniquement si un humain les a activés
clé restreinte rk_test_… / rk_live_…, ou une connexion OAuth	la même chose, réduite aux scopes qu’un humain a accordés dans le tableau de bord (par ex. payments:read + payments:write uniquement). Les remboursements n’apparaissent que si refunds:write a été accordé
ak_test_… / ak_live_… portefeuille d’agent	sa propre politique et son solde, et des versements dans les limites du plafond par versement, du plafond journalier, de la liste de bénéficiaires et du solde fixés par un humain

Les identifiants de test vont vers l’API sandbox, ceux de production vers la production — automatiquement.

Moindre privilège : pour un agent en production, préférez une clé restreinte (tableau de bord → API keys → restricted, choisissez les scopes) ou une connexion OAuth à une clé sk_live_ complète. Scopes : payments:read, payments:write, refunds:write, subscriptions:read, subscriptions:write, payouts:read, balance:read, webhooks:read, agent_wallets:read, agent_wallets:write (ainsi que payouts:write et webhooks:write, que les outils MCP n’utilisent pas).

Les remboursements en production avec une clé sk_live_ complète sont désactivés tant que l’humain qui configure la connexion ne les active pas : en-tête X-Xaalis-Allow-Live-Refunds: true (hébergé) ou XAALIS_ALLOW_LIVE_REFUNDS=true (local). Avec une clé restreinte ou OAuth, accorder refunds:write constitue cette décision. Le modèle ne peut modifier ni l’un ni l’autre.

L’argent sortant passe uniquement par les portefeuilles d’agent : un solde séparé (le budget total de l’agent), un plafond par versement, un plafond journalier facultatif et une liste autorisée de numéros de téléphone, avec une clé qui ne peut rien faire d’autre. Relancer le même action_id ne paie jamais deux fois. En production, seul un propriétaire (owner) du tableau de bord peut créer un portefeuille d’agent, l’approvisionner et émettre ses clés — jamais une clé API : un agent ne peut donc pas s’approvisionner lui-même. Voir Portefeuilles d’agent.

Règles suivies par chaque agent

Le serveur les envoie comme instructions MCP ; les skills les répètent.

1. Les montants sont des entiers en XOF (15000), jamais des décimaux.
2. Chaque écriture prend une idempotency_key dérivée de l’action métier ; les nouvelles tentatives la réutilisent.
3. Un paiement n’est payé que lorsqu’il indique succeeded (ou qu’un webhook signé le dit) — jamais à cause d’une redirection.
4. Les clés de test manipulent de l’argent fictif. Avec une clé de production, confirmez le montant et l’objet avec l’humain avant toute écriture.
5. L’argent ne sort que par les portefeuilles d’agent.
6. outcome_unknown: true → lisez l’objet ou relancez avec la même clé ; n’en créez jamais un second.
7. Les clés secrètes restent dans des variables d’environnement ou un coffre à secrets — jamais dans la conversation, le code ou les logs.

Démarrer sans humain (sandbox)

Connectez-vous sans clé. L’agent appelle xaalis_sandbox_signup avec une adresse e-mail et un nom d’entreprise, et obtient un compte sandbox (clé sk_test_… + secret de webhook). La même session bascule dessus : l’agent peut donc enchaîner directement — créer un paiement, simuler le paiement du client, le rembourser, mettre en place un abonnement.

• Serveur local : la session garde la clé jusqu’à l’arrêt du processus.
• Serveur hébergé : connectez-vous à https://mcp.xaalis.org/sandbox sans identifiant. La session (Mcp-Session-Id) garde la clé sandbox en mémoire jusqu’à 30 minutes d’inactivité. C’est ce qu’utilisent les clients configurés « sans authentification » (ChatGPT, claude.ai) ; les outils sandbox sont listés dès le départ et répondent signup_required jusqu’à l’inscription.
• Pour garder le compte, enregistrez la secret_key renvoyée dans XAALIS_API_KEY et reconnectez-vous avec.

Passer en production demande toujours un humain : vérification d’identité (KYC), validation, puis une clé de production.

Connecter votre client

Point d’accès hébergé	Identifiant
https://mcp.xaalis.org/mcp	Authorization: Bearer <key> (sk_, rk_, ak_), ou OAuth : sans identifiant, il répond 401 et les clients compatibles OAuth ouvrent la page de connexion Xaalis, où vous choisissez le compte, test ou production, et les scopes
https://mcp.xaalis.org/sandbox	aucun — la session sandbox sans humain

Local : npx -y @xaalis/mcp (Node 20+) avec la clé dans XAALIS_API_KEY. Omettez la clé pour démarrer sans humain.

Claude Code

claude mcp add --transport http xaalis https://mcp.xaalis.org/mcp --header "Authorization: Bearer $XAALIS_API_KEY"
# ou en local :
claude mcp add --env XAALIS_API_KEY=$XAALIS_API_KEY --transport stdio xaalis -- npx -y @xaalis/mcp

Ou installez le plugin (serveur MCP + skills ; la clé est demandée une seule fois et conservée dans le gestionnaire d’identifiants de votre système) :

/plugin marketplace add <path-or-repo-with-integrations/ai>
/plugin install xaalis@xaalis

Fichier .mcp.json du projet (partagé avec votre équipe — la clé reste dans l’environnement de chacun) :

{
  "mcpServers": {
    "xaalis": { "type": "http", "url": "https://mcp.xaalis.org/mcp", "headers": { "Authorization": "Bearer ${XAALIS_API_KEY}" } }
  }
}

Claude Desktop et claude.ai

Serveur local — claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\) :

{ "mcpServers": { "xaalis": { "command": "npx", "args": ["-y", "@xaalis/mcp"], "env": { "XAALIS_API_KEY": "sk_test_…" } } } }

Connecteur personnalisé distant (Customize → Connectors → Add custom connector) :

• votre compte : URL https://mcp.xaalis.org/mcp — Claude ouvre la page de connexion Xaalis (OAuth). Vous choisissez le compte, test ou production, et ce que le connecteur a le droit de faire (scopes). Retirer ce consentement prend effet immédiatement.
• pas encore de compte : URL https://mcp.xaalis.org/sandbox sans connexion — la session sandbox sans humain.

ChatGPT

Plugins → Add → Add custom MCP server (le mode développeur n’est plus nécessaire) :

• votre compte : URL https://mcp.xaalis.org/mcp, authentification OAuth — ChatGPT découvre seul la page de connexion Xaalis ; vous choisissez le compte, test ou production, et les scopes.
• pas encore de compte : URL https://mcp.xaalis.org/sandbox, No authentication — l’agent cherche dans la documentation, ouvre un compte sandbox et l’utilise dans cette conversation.

Ce que demande la connexion Xaalis (OAuth)

Vérifié de bout en bout avec Claude.ai et ChatGPT le 14/10/2026 :

• Seul un propriétaire de la boutique peut autoriser un connecteur ; un membre avec un autre rôle voit « Autorisation non disponible ».
• Vous choisissez la boutique et test ou live (live seulement une fois la boutique activée), puis décochez les autorisations que vous ne voulez pas donner — par exemple gardez payments:read, balance:read et payments:write, et laissez décochés les remboursements, virements et portefeuilles d’agents. Le connecteur reçoit exactement ce qui reste coché.
• Validez dans les 10 minutes après « Connect » ; au-delà la demande expire (« Erreur de continuation OAuth ») et il faut recommencer depuis « Connect ».
• Les jetons d’accès durent 5 minutes et sont renouvelés en arrière-plan (offline_access). Réglages → Applications & IA → Révoquer l’accès coupe le connecteur immédiatement — son appel suivant échoue même avec un jeton encore valide.

Cursor

.cursor/mcp.json (projet) ou ~/.cursor/mcp.json :

{
  "mcpServers": {
    "xaalis": { "url": "https://mcp.xaalis.org/mcp", "headers": { "Authorization": "Bearer ${env:XAALIS_API_KEY}" } }
  }
}

En local à la place : { "command": "npx", "args": ["-y", "@xaalis/mcp"], "env": { "XAALIS_API_KEY": "${env:XAALIS_API_KEY}" } }.

VS Code (GitHub Copilot)

.vscode/mcp.json — attention, la clé de premier niveau est servers ; VS Code demande la clé une seule fois et la conserve :

{
  "inputs": [{ "type": "promptString", "id": "xaalis-key", "description": "Xaalis API key", "password": true }],
  "servers": {
    "xaalis": { "type": "http", "url": "https://mcp.xaalis.org/mcp", "headers": { "Authorization": "Bearer ${input:xaalis-key}" } }
  }
}

OpenAI Codex CLI

~/.codex/config.toml :

[mcp_servers.xaalis]
url = "https://mcp.xaalis.org/mcp"
bearer_token_env_var = "XAALIS_API_KEY"

# ou en local :
# [mcp_servers.xaalis]
# command = "npx"
# args = ["-y", "@xaalis/mcp"]
# env_vars = ["XAALIS_API_KEY"]

Gemini CLI

~/.gemini/settings.json ou .gemini/settings.json :

{
  "mcpServers": {
    "xaalis": { "httpUrl": "https://mcp.xaalis.org/mcp", "headers": { "Authorization": "Bearer $XAALIS_API_KEY" } }
  }
}

Windsurf / Devin Desktop

~/.config/devin/mcp_config.json (anciennes versions de Windsurf : ~/.codeium/windsurf/mcp_config.json) :

{
  "mcpServers": {
    "xaalis": { "serverUrl": "https://mcp.xaalis.org/mcp", "headers": { "Authorization": "Bearer ${env:XAALIS_API_KEY}" } }
  }
}

Zed

settings.json :

{
  "context_servers": {
    "xaalis": { "command": "npx", "args": ["-y", "@xaalis/mcp"], "env": { "XAALIS_API_KEY": "sk_test_…" } }
  }
}

API OpenAI et Agents SDK

Responses API — OpenAI appelle les outils lui-même :

await openai.responses.create({
  model: "gpt-5",
  input: "Crée un paiement de 15000 F CFA pour 'Tissus wax' et donne-moi le lien.",
  tools: [{
    type: "mcp",
    server_label: "xaalis",
    server_url: "https://mcp.xaalis.org/mcp",
    headers: { Authorization: `Bearer ${process.env.XAALIS_API_KEY}` },
    require_approval: "always", // gardez "always" avec les clés de production
  }],
});

Agents SDK : new MCPServerStreamableHttp({ url: "https://mcp.xaalis.org/mcp", requestInit: { headers: { Authorization: … } } }) (TypeScript) ou MCPServerStreamableHttp(params={"url": …, "headers": {…}}) (Python).

API Anthropic

Connecteur MCP (en-tête bêta mcp-client-2025-11-20) :

{
  "mcp_servers": [{ "type": "url", "url": "https://mcp.xaalis.org/mcp", "name": "xaalis", "authorization_token": "sk_test_…" }],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "xaalis" }]
}

Des versions complètes et exécutables de ces exemples se trouvent dans integrations/ai/examples/ du dépôt Xaalis.

Skills pour les agents de code

Deux Agent Skills, incluses dans le plugin Claude Code et utilisables par tout agent qui prend en charge les skills :

• xaalis-integration — ajouter Xaalis à une application : création du paiement côté serveur, redirection, vérification des webhooks (Node, Python, PHP, Go), livraison de la commande, tests en sandbox, remboursements, abonnements, versements, passage en production.
• xaalis-operations — gérer une activité avec les outils MCP : encaisser et confirmer, rembourser, abonnements, solde, débogage des webhooks, versements par portefeuille d’agent, gestion des erreurs.

Pour les agents qui lisent AGENTS.md (Codex, Gemini CLI, Copilot, Jules…), collez la section toute prête integrations/ai/AGENTS.xaalis.md dans le vôtre. Cursor : integrations/ai/cursor/xaalis.mdc → .cursor/rules/.

Votre propre agent (sans MCP)

Le même catalogue d’outils fonctionne directement dans votre processus : vous transmettez les définitions d’outils à votre modèle et vous exécutez ses appels.

TypeScript — @xaalis/ai-tools :

import { AGENT_RULES, XaalisToolkit } from "@xaalis/ai-tools";
import { openAITools, runOpenAIToolCall } from "@xaalis/ai-tools/openai";      // Responses / Chat Completions
import { anthropicTools, runAnthropicToolUse } from "@xaalis/ai-tools/anthropic";
import { vercelTools } from "@xaalis/ai-tools/vercel";                          // AI SDK : tools: vercelTools(kit)
import { langChainTools } from "@xaalis/ai-tools/langchain";                    // nécessite @langchain/core

const kit = new XaalisToolkit({ apiKey: process.env.XAALIS_API_KEY });         // sans clé : docs + inscription sandbox
// clé restreinte (rk_) ou jeton OAuth : const kit = await XaalisToolkit.connect({ apiKey }) — charge ses scopes
const tools = openAITools(kit);                                                 // à passer au modèle
const output = await runOpenAIToolCall(kit, call.name, call.arguments);         // exécute ce qu'il appelle

Python — xaalis.ai (bibliothèque standard uniquement) :

from xaalis.ai import AGENT_RULES, XaalisToolkit

kit = XaalisToolkit(os.environ.get("XAALIS_API_KEY"), allow_live_refunds=False)
tools = kit.openai_tools()            # ou openai_chat_tools(), anthropic_tools(), langchain_tools()
output = kit.run_for_model(call.name, call.arguments)

Les résultats sont en JSON ; les erreurs reviennent sous la forme {"error": {"code", "message", "hint", "outcome_unknown"}} pour que le modèle sache quoi faire ensuite. Après une inscription sandbox, reconstruisez la liste d’outils (kit.tools() change).

Référence des outils

Colonne Clés : sk = clés marchand (ainsi que clés restreintes / OAuth avec le scope correspondant), ak = clés de portefeuille d’agent.

Outil	Clés	Rôle
xaalis_whoami	toutes	clé connectée, mode, compte/portefeuille, outils disponibles
xaalis_search_docs	toutes	chercher dans cette documentation
xaalis_sandbox_signup	aucune	créer un compte sandbox (e-mail, nom d’entreprise)
xaalis_create_payment · _get_payment · _list_payments	sk	paiement + checkout_url ; statut
xaalis_simulate_payment	sk_test	faire réussir ou échouer un paiement de test
xaalis_refund_payment · _list_refunds	sk (production : si autorisé)	remboursement total d’un paiement Wave ; le suivre
xaalis_get_balance	sk	XOF disponibles et réservés
xaalis_create_payout	sk_test	versement depuis le solde du marchand (sandbox)
xaalis_get_payout · _list_payouts	sk	statut des versements
xaalis_list_webhook_deliveries	sk	webhooks récents, tentatives, dernière erreur
xaalis_create_subscription · _get_subscription · _list_subscriptions · _cancel_subscription	sk	abonnements et paiements échelonnés
xaalis_advance_subscription	sk_test	passer directement au prochain événement de facturation
xaalis_get_invoice · _list_invoices	sk	factures et leur lien de paiement stable
xaalis_create_agent_wallet · _fund_agent_wallet · _reclaim_agent_wallet · _issue_agent_key	sk_test	configurer un portefeuille d’agent (en production : un humain, dans le tableau de bord)
xaalis_disable_agent_wallet · _list_agent_wallets · _get_agent_wallet	sk	arrêter et consulter les portefeuilles d’agent
xaalis_agent_get_wallet · _agent_pay · _agent_get_payout · _agent_list_payouts	ak	le portefeuille et les versements de l’agent lui-même

Ressources : xaalis://rules, xaalis://docs/llms.txt, xaalis://docs/llms-full.txt, xaalis://openapi.json. Prompts : accept_payment, integrate_xaalis, sandbox_tour.

Notes de sécurité

• Le serveur hébergé ne conserve rien : une requête avec une clé ou un jeton est traitée puis oubliée ; une session anonyme /sandbox ne détient qu’une clé sandbox, en mémoire. Les clés, les jetons et le contenu des requêtes ne sont jamais journalisés.
• Les jetons OAuth durent cinq minutes (les clients les renouvellent). Le serveur vérifie leur signature et leur audience, et l’API revérifie le consentement, l’appartenance au compte et les scopes à chaque appel — un consentement retiré prend effet immédiatement.
• Une clé de production n’est jamais envoyée autrement qu’en HTTPS.
• Donnez à un agent le strict nécessaire : une clé sandbox pour développer et tester ; en production, une clé de production (argent entrant) et, s’il doit payer des personnes, son propre portefeuille d’agent avec un petit solde et un plafond. Désactivez le portefeuille pour l’arrêter immédiatement.
• Considérez tout ce que l’agent lit (pages web, e-mails, documents) comme non fiable : cela ne peut pas débloquer des outils que sa clé n’a pas, mais vérifiez ce qu’il propose avant d’approuver des actions en production.