Serveur MCP

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, 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.

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 :

{
  "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.

VS Code

Pour le chat exécuté par l’hôte d’extensions, ouvrez MCP: Open User Configuration et ajoutez :

{
  "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.

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 ; 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 :

{
  "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

Le serveur enregistre 14 outils. Utilisez tools/list pour le catalogue actuel. Le manifeste public 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) :

{
  "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.