@avetrust/mcp

Serveur MCP officiel d'AveTrust — pilotez la vérification d'identité (eKYC) directement depuis Claude (Desktop / Code) ou tout agent compatible MCP.

Transport stdio (local). Il enveloppe le SDK @avetrust/node et expose l'API comme des outils appelables en langage naturel.

Garde-fous (KYC = données sensibles)

• 🧪 Sandbox par défaut — les écritures en sk_live_ sont bloquées tant que AVETRUST_ALLOW_LIVE=true n'est pas défini.
• 🔒 PII masquée — les valeurs extraites (nom, n° de pièce, date de naissance…) ne sont jamais renvoyées à l'agent ; seuls le verdict, les scores et la liste des champs le sont. AVETRUST_ALLOW_PII=true pour lever le masque.
• ✋ decide = confirmation humaine — approuver/rejeter une identité est irréversible et exige confirm=true (enjeu réglementaire AML/KYC).
• 🔑 Clé par variable d'environnement, jamais en argument d'outil.

Installation

npm i -g @avetrust/mcp

Configuration Claude Desktop

Dans claude_desktop_config.json :

{
  "mcpServers": {
    "avetrust": {
      "command": "avetrust-mcp",
      "env": { "AVETRUST_API_KEY": "sk_test_…" }
    }
  }
}

Configuration Claude Code

claude mcp add avetrust --env AVETRUST_API_KEY=sk_test_… -- avetrust-mcp

Variables d'environnement

| Variable | Rôle | Défaut | |---|---|---| | AVETRUST_API_KEY | Clé API (sk_test_… recommandé). | — (requis) | | AVETRUST_BASE_URL | Surcharge l'URL API. | api-test.avetrust.net | | AVETRUST_ALLOW_LIVE | true pour autoriser les écritures avec une clé sk_live_. | false | | AVETRUST_ALLOW_PII | true pour exposer les valeurs extraites (déconseillé). | false |

Outils

| Outil | Description | Type | |---|---|---| | avetrust_status | Mode courant + garde-fous. À appeler en premier. | lecture | | create_verification | Crée une session (checks, simulate…). | écriture | | get_verification | Résumé d'une session. | lecture | | get_result | Résultat complet (verdict, scores) — PII masquée. | lecture | | list_verifications | Liste paginée (status, test). | lecture | | send_verification_link | Envoie le lien hébergé (EMAIL/SMS). | écriture | | decide_verification | Décision manuelle — exige confirm=true. | écriture |

Exemples de prompts

• « Quel est le statut du serveur AveTrust ? »
• « Crée une vérification DOCUMENT + LIVENESS pour le client 'user_42', simulate approved, et donne-moi le lien. »
• « Liste les 10 dernières sessions en REVIEW en sandbox. »
• « Montre-moi le résultat de la session sess_…. » (sans exposer la PII)

Déploiement distant (Streamable HTTP)

Le même serveur s'expose en HTTP distant (avetrust-mcp-http, port 8080) pour un usage multi-tenant ou une intégration au Directory Claude.

# local
npm run start:http           # → http://localhost:8080/mcp
# conteneur
docker build -t avetrust-mcp . && docker run -p 8080:8080 avetrust-mcp
# kubernetes
kubectl apply -f deploy/k8s/mcp.yaml   # Ingress mcp.avetrust.net + TLS cert-manager

Endpoints : POST/GET/DELETE /mcp (protocole), GET /healthz, GET /.well-known/oauth-protected-resource (si OAuth activé).

Palier 2 — clé par en-tête (multi-tenant)

Chaque client apporte sa clé AveTrust dans un en-tête (jamais dans le corps ni l'URL) :

| En-tête | Rôle | |---|---| | X-AveTrust-Api-Key | Clé sk_test_… / sk_live_… du tenant (requis). | | X-AveTrust-Allow-Live | true pour autoriser les écritures en live. | | X-AveTrust-Allow-Pii | true pour exposer les valeurs extraites. |

Sans clé → 401.

Palier 3 — OAuth 2.1 (Keycloak) pour le Directory Claude

Active la protection par jeton (le serveur devient une Resource Server OAuth ; l'Authorization Server est votre Keycloak) :

OAUTH_ENABLED=true \
OAUTH_ISSUER=https://auth-test.avetrust.net/realms/avetrust \
OAUTH_AUDIENCE=https://mcp.avetrust.net/mcp \
MCP_RESOURCE_URL=https://mcp.avetrust.net/mcp \
npm run start:http

Le serveur vérifie le Bearer JWT contre le JWKS Keycloak, expose les métadonnées RFC 9728, et répond 401 + WWW-Authenticate conforme à la spec MCP. La correspondance tenant → clé AveTrust se fait via le claim avetrust_api_key (à émettre par un mapper Keycloak). Voir docs/PALIER-3-DIRECTORY.md.

Licence

MIT © AveTrust