RefCampaign héberge un endpoint Model Context Protocol (MCP) pour vous permettre de gérer votre programme directement depuis Claude Desktop et tout autre client LLM compatible MCP. Aucun téléchargement, aucune installation Node — il suffit de coller une URL.

## Ce que vous pouvez faire

Quatorze tools exposés :

| Tool                                                      | Cas d'usage                                                 |
| --------------------------------------------------------- | ----------------------------------------------------------- |
| `get_dashboard_summary`                                   | « Comment va mon programme ce mois-ci ? »                   |
| `list_campaigns`, `get_campaign`                          | Vue d'ensemble d'une campagne                               |
| `list_conversions`, `get_conversions_summary`             | Drill-down sur les conversions, comparaison périodique      |
| `list_commissions`                                        | Trier ce qui nécessite review                               |
| `approve_commissions` (bulk), `reject_commissions` (bulk) | « Approuve toutes les commissions PENDING sous 50€ de mai » |
| `list_affiliates`, `get_affiliate`                        | Inspecter les stats d'un affilié spécifique                 |
| `list_pending_applications`                               | Trouver les candidatures en attente                         |
| `accept_application`, `reject_application`                | Accepter ou refuser une candidature                         |
| `accept_applications` (bulk)                              | Onboarder plusieurs candidats d'un coup                     |

Les tools de bulk write fonctionnent par défaut en **mode dry-run** : ils affichent le nombre de lignes qui seraient affectées sans rien modifier. Passez `confirm: true` pour exécuter. Couplé au prompt de permission par tool de Claude Desktop, vous avez un double filet de sécurité avant toute mutation.

## Découverte

Pour les clients agents qui découvrent automatiquement les endpoints MCP, RefCampaign publie un manifeste machine-readable à [`/.well-known/mcp.json`](https://app.refcampaign.com/.well-known/mcp.json) :

```bash
curl https://app.refcampaign.com/.well-known/mcp.json | jq .
```

Le manifeste déclare l'URL de l'endpoint, le transport (`streamable-http`), le schéma d'authentification (`bearer`) et la liste complète des slugs de tools. Il est volontairement statique : n'importe quel client HTTP peut le récupérer sans authentification.

## Installation

<Steps>
  <Step>
    ### Générez une clé API

    Rendez-vous dans [Paramètres → Clés API](https://app.refcampaign.com/dashboard/settings/api) et créez une nouvelle clé. Copiez-la immédiatement — elle est stockée hashée et ne sera plus affichée ensuite.
  </Step>

  <Step>
    ### Éditez votre config Claude Desktop

    Ouvrez le fichier :

    * **macOS** : `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows** : `%APPDATA%\Claude\claude_desktop_config.json`

    Ajoutez l'entrée RefCampaign sous `mcpServers` :

    ```json
    {
      "mcpServers": {
        "refcampaign": {
          "url": "https://app.refcampaign.com/api/mcp",
          "headers": {
            "Authorization": "Bearer rcm_live_xxxxxxxxxxxx"
          }
        }
      }
    }
    ```

    Remplacez `rcm_live_...` par votre clé API.
  </Step>

  <Step>
    ### Redémarrez Claude Desktop

    Les 14 tools RefCampaign devraient apparaître dans le picker. Tapez une requête en langage naturel, par exemple :

    > « Approuve toutes mes commissions en attente sous 50€ de mai. »

    Claude choisira le bon tool, fera un dry-run d'abord, puis vous demandera la permission avant d'exécuter.
  </Step>
</Steps>

## Authentification, scopes et rate limit

* Chaque requête nécessite `Authorization: Bearer <clé-api>` — aucun accès anonyme.
* Rate limit par compte : **1000 requêtes par minute**, fenêtre glissante. Le client MCP retry une fois sur 429 si le `Retry-After` est court ; sinon il remonte l'erreur au LLM.
* Body de requête capé à **1 Mo** — les payloads JSON-RPC sont minuscules en pratique, c'est une marge de sécurité.
* Toutes les actions sont scopées à votre compte merchant — aucun risque de fuite de données entre merchants.

### Scopes des clés API

Si votre clé API a des scopes attachés :

* `mcp:read` — requis pour les tools de lecture (list / get / summary).
* `mcp:write` — requis pour les tools bulk approve / reject / accept.
* `*` (wildcard) ou aucun scope — accès complet (défaut rétrocompatible).

Les clés à scope restreint sont utiles quand vous voulez donner à Claude Desktop un accès lecture seule pour le reporting sans risquer une approbation accidentelle. Générez une clé `mcp:read` séparée de votre clé principale et swappez le header quand vous voulez le mode strict read-only.

## Troubleshooting

**« Invalid API key » au premier appel** → la clé a été révoquée, jamais générée, ou copiée avec une erreur. Régénérez sur [Paramètres → Clés API](https://app.refcampaign.com/dashboard/settings/api).

**Aucun tool n'apparaît après installation** → vérifiez les logs développeur de Claude Desktop (Help → Show Logs). La plupart des problèmes viennent d'une typo dans `claude_desktop_config.json` ; validez le JSON avec `cat $config | jq` avant.

**429 Too Many Requests** → vous avez dépassé 1000 requêtes/minute sur la clé API. Patientez une minute ou générez une clé séparée pour une autre intégration.

## Confidentialité

L'endpoint MCP hébergé voit uniquement les requêtes que votre Claude Desktop envoie. Nous logguons les requêtes au même niveau que le reste de notre API (account ID, nom du tool, statut de la réponse — jamais les prompts que vous tapez dans Claude Desktop). La conversation entre vous et Claude reste entre vous et Anthropic.