RefCampaign héberge un endpoint **Streamable HTTP** à l’adresse `https://app.refcampaign.com/api/mcp`. Il nécessite une clé API marchand dans le header `Authorization` et un droit d’abonnement actif. Aucun serveur RefCampaign local n’est nécessaire. ## Permissions Dans [Paramètres → Clés API](https://app.refcampaign.com/dashboard/settings/api), décochez **API : lecture** et sélectionnez **MCP : lecture** pour le reporting. Ajoutez **MCP : écriture** uniquement si l’assistant doit modifier des commissions ou candidatures. Copiez le secret lors de la création. Cette opération ne modifie ni ne révoque les clés existantes. | Scope | Accès | | ---------------------------------------- | ------------------------------------------------------- | | `mcp:read` | Outils de lecture | | `mcp:write` | Outils d’écriture, y compris leurs simulations | | Les deux | Lecture et écriture | | `*` | Accès complet pour les clés existantes portant ce scope | | Aucun, ou seulement `read` / `write` API | Aucun accès aux outils MCP | Les scopes sont vérifiés à l’exécution. Un outil visible n’est pas nécessairement autorisé. ## Configuration des clients Les exemples suivent les références des clients ci-dessous. Ils ne signifient pas que chaque version de client a été testée avec RefCampaign. ### Claude Code Ajoutez cette entrée au fichier `.mcp.json` du projet, en conservant les serveurs existants : ```json { "mcpServers": { "refcampaign": { "type": "http", "url": "https://app.refcampaign.com/api/mcp", "headers": { "Authorization": "Bearer ${REFCAMPAIGN_MCP_KEY}" } } } } ``` Fournissez `REFCAMPAIGN_MCP_KEY` via votre gestionnaire de secrets dans l’environnement qui lance Claude Code. Gardez la référence à la variable dans le fichier ; ne commitez jamais de secret. Vérifiez la connexion avec `/mcp`. Consultez la [référence MCP de Claude Code](https://code.claude.com/docs/en/mcp). ### VS Code Pour le chat exécuté par l’hôte d’extensions, ouvrez **MCP: Open User Configuration** et ajoutez : ```json { "inputs": [ { "type": "promptString", "id": "refcampaign-key", "description": "Clé API MCP RefCampaign", "password": true } ], "servers": { "refcampaign": { "type": "http", "url": "https://app.refcampaign.com/api/mcp", "headers": { "Authorization": "Bearer ${input:refcampaign-key}" } } } } ``` Démarrez le serveur avec **MCP: List Servers** et saisissez la clé dans le champ masqué. L’Agent Host ne reçoit pas les serveurs nécessitant une saisie interactive ; cet exemple concerne l’hôte d’extensions. Consultez la [référence MCP de VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ### Claude Desktop et claude.ai Ces exemples ne sont pas des entrées pour `claude_desktop_config.json`. Les serveurs locaux Desktop et les connecteurs distants ont des procédures distinctes. RefCampaign utilise une clé Bearer statique, sans flux OAuth MCP. Ne supposez pas qu’un connecteur limité à OAuth peut l’utiliser. Consultez le [guide des connecteurs distants d’Anthropic](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) ; utilisez un client acceptant les headers comme ci-dessus pour ce guide. ## Vérifier une lecture Avec seulement `mcp:read`, demandez : « Liste mes campagnes sans rien modifier. » Les paramètres `tools/call` correspondants sont : ```json { "name": "list_campaigns", "arguments": {} } ``` Pour le staging, utilisez `https://app.test.refcampaign.com/api/mcp` avec une clé staging `rc_test_`. N’envoyez jamais de clé de production au staging. Une connexion ou un `tools/list` ne suffit pas : vérifiez qu’une lecture réussit. ## Outils et découverte | Outils | Scope | | ----------------------------------------------------------------- | ----------- | | `get_dashboard_summary` | `mcp:read` | | `list_campaigns`, `get_campaign` | `mcp:read` | | `list_conversions`, `get_conversions_summary` | `mcp:read` | | `list_commissions` | `mcp:read` | | `list_affiliates`, `get_affiliate` | `mcp:read` | | `list_pending_applications` | `mcp:read` | | `approve_commissions`, `reject_commissions` | `mcp:write` | | `accept_application`, `reject_application`, `accept_applications` | `mcp:write` | Le serveur enregistre 14 outils. Utilisez `tools/list` pour le catalogue actuel. Le [manifeste public](https://app.refcampaign.com/.well-known/mcp.json) décrit l’endpoint, le transport, l’authentification et les noms d’outils. La découverte automatique dépend du client. ## Confirmation des écritures `approve_commissions`, `reject_commissions` et `accept_applications` utilisent `confirm: false` par défaut. Même leurs simulations nécessitent `mcp:write`. Délimitez les opérations avec les identifiants renvoyés par une lecture. Ces paramètres `tools/call` simulent l’approbation d’une commission (remplacez l’identifiant d’exemple) : ```json { "name": "approve_commissions", "arguments": { "commission_ids": [ "cl00000000000000000000001" ], "confirm": false } } ``` Vérifiez la simulation, puis renvoyez les mêmes identifiants avec `confirm: true` uniquement si vous voulez les approuver. Le serveur n’impose pas de simulation préalable et ne réserve pas les enregistrements entre les appels. **`accept_application` et `reject_application` s’exécutent immédiatement** avec `mcp:write` ; ils n’ont pas de paramètre `confirm`. Les demandes d’approbation dépendent des réglages du client. Utilisez une clé en lecture seule pour le reporting. ## Dépannage * **401 :** clé absente, expirée, révoquée ou mal transmise. * **402 :** le marchand doit disposer d’un droit d’abonnement actif. * **Scope manquant :** créez une clé avec la permission MCP requise ; les scopes API ne donnent pas accès au MCP. * **429 :** respectez `Retry-After` lorsqu’il est fourni et attendez la fin de la fenêtre concernée. La limite authentifiée est de 1 000 requêtes/minute **par compte**, partagée entre ses clés. Une limite IP distincte intervient avant l’authentification. Les nouvelles tentatives dépendent du client. * **405 / 413 :** utilisez Streamable HTTP POST, pas l’ancien SSE GET. La route refuse un `Content-Length` déclaré supérieur à 1 Mo ; une limite d’hébergement distincte s’applique aussi. GET et DELETE ne sont pas implémentés. ## Données transmises au client Les outils renvoient les données marchand, dont les informations des affiliés, conversions et commissions, à votre client et potentiellement à son fournisseur de modèle. RefCampaign reçoit les arguments des outils, qui peuvent contenir des éléments de votre conversation. Consultez la politique de données du client et accordez uniquement les permissions nécessaires.