# Serveur MCP

> Laissez Claude Code, Cursor, VS Code et d'autres agents IA gérer formulaires, soumissions et webhooks via le serveur MCP d'Ikiform.

Ikiform exploite un serveur [Model Context Protocol](https://modelcontextprotocol.io) distant. Connectez-le à un agent IA et l'agent peut créer, brancher et configurer des formulaires, lire et trier les soumissions, et configurer et déboguer les webhooks de votre espace de travail, avec les mêmes clés secrètes et les mêmes portées que l'[API REST](https://ikiform.com/fr/docs/api.md).

|   |   |
| --- | --- |
| URL | `https://ikiform.com/mcp` |
| Transport | Streamable HTTP, sans état, JSON-RPC via `POST` |
| Authentification | `Authorization: Bearer ik_sk_...` |
| Limite de débit | 100 requêtes par minute et par clé, partagées avec l'API REST |

## Créer une clé

Dans le [tableau de bord](https://ikiform.com/dashboard/api-keys), créez une clé **secrète** et ne lui donnez que les portées dont l'agent a besoin. Chaque outil agit sur l'espace de travail auquel appartient la clé. Gardez la clé hors de votre dépôt : utilisez une variable d'environnement ou la saisie de secret de votre client.

| Portée | Outils |
| --- | --- |
| `forms:read` | `list_forms`, `get_form` et `connect_form` avec un `form_id` |
| `forms:write` | `create_form`, `update_form`, `set_form_fields`, `delete_form` |
| `submissions:read` | `list_submissions`, `get_submission` |
| `submissions:write` | `mark_spam`, `mark_not_spam`, `delete_submission` |
| `webhooks:read` | `list_webhook_endpoints`, `list_deliveries` |
| `webhooks:write` | `create_webhook_endpoint` et `update_webhook_endpoint` (avec `submissions:read`), `roll_webhook_secret`, `delete_webhook_endpoint`, `send_test_event`, `replay_failed_deliveries` |

> Pour connecter des formulaires dans votre code, `forms:read` et `forms:write` suffisent. Pour un tri en lecture seule, utilisez `submissions:read`. Un outil appelé sans sa portée renvoie une erreur `forbidden` qui nomme la portée manquante.

## Connecter votre client

**Claude Code** (`Terminal`)

```bash
claude mcp add --transport http ikiform https://ikiform.com/mcp \
  --header "Authorization: Bearer ik_sk_..."
```

**Cursor** (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "ikiform": {
      "url": "https://ikiform.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:IKIFORM_API_KEY}"
      }
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "ikiform-api-key",
      "description": "Ikiform secret API key (ik_sk_...)",
      "password": true
    }
  ],
  "servers": {
    "ikiform": {
      "type": "http",
      "url": "https://ikiform.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:ikiform-api-key}"
      }
    }
  }
}
```

**Autres clients** (`mcp.json`)

```json
{
  "mcpServers": {
    "ikiform": {
      "type": "http",
      "url": "https://ikiform.com/mcp",
      "headers": { "Authorization": "Bearer ik_sk_..." }
    }
  }
}
```

Dans Cursor, définissez `IKIFORM_API_KEY` dans votre environnement. VS Code demande la clé la première fois et la stocke de façon sécurisée. Tout client qui prend en charge les serveurs HTTP distants avec des en-têtes personnalisés fonctionne de la même manière.

Ikiform figure dans le [registre MCP officiel](https://registry.modelcontextprotocol.io/v0/servers?search=ikiform) sous le nom `io.github.preetsuthar17/ikiform`. Dans Claude Code, le [plugin Ikiform](https://github.com/preetsuthar17/ikiform-plugin) ajoute le serveur et un skill pour connecter vos formulaires : lancez `claude plugin marketplace add preetsuthar17/ikiform-plugin`, puis `claude plugin install ikiform@ikiform`.

## Outils

Les id ressemblent à `frm_...` pour les formulaires, `sub_...` pour les soumissions, `whk_...` pour les endpoints de webhook et `dlv_...` pour les livraisons. Les listes renvoient 25 éléments par défaut et 100 au maximum ; quand `has_more` vaut true, passez `next_cursor` comme `cursor`.

| Outil | Rôle |
| --- | --- |
| `list_forms` | Les formulaires, du plus récent au plus ancien, avec id, nom, statut, nombre de soumissions et endpoint |
| `get_form` | L'endpoint, les champs, le champ honeypot, les domaines autorisés, l'URL de redirection, les extraits de code et les instructions de mise en place d'un formulaire |
| `create_form` | Crée un formulaire à partir d'un nom, avec des domaines autorisés et une URL de redirection facultatifs |
| `update_form` | Met un formulaire en pause ou le reprend, et modifie son nom, ses domaines autorisés, son URL de redirection, sa vérification anti-spam, ses limites de débit ou ses notifications par e-mail |
| `set_form_fields` | Publie un schéma de champs par rapport auquel les envois sont validés, ou le supprime |
| `delete_form` | Supprime un formulaire. Son endpoint cesse d'accepter les envois |
| `list_submissions` | Les soumissions, de la plus récente à la plus ancienne, filtrées par formulaire, statut (`received` ou `spam`) ou date |
| `get_submission` | Une soumission avec ses champs, ses métadonnées et son score de spam |
| `mark_spam`, `mark_not_spam` | Déplace une soumission vers le spam ou l'en sort, en envoyant les webhooks correspondants |
| `delete_submission` | Supprime définitivement une soumission. Action irréversible |
| `list_webhook_endpoints` | Les endpoints avec leur URL, leur statut, leurs événements et leur état d'échec. Les secrets ne sont jamais renvoyés |
| `create_webhook_endpoint` | Ajoute un endpoint et renvoie une seule fois son secret de signature |
| `update_webhook_endpoint` | Modifie l'URL, le formulaire, les événements ou les en-têtes personnalisés d'un endpoint, ou le désactive et le réactive |
| `roll_webhook_secret` | Renvoie un nouveau secret de signature. L'ancien continue de fonctionner pendant 24 heures |
| `delete_webhook_endpoint` | Supprime un endpoint et son historique de livraisons |
| `list_deliveries` | Les livraisons récentes d'un endpoint, avec statut, tentatives et dernière erreur |
| `send_test_event` | Envoie un événement `endpoint.test` signé à un endpoint actif |
| `replay_failed_deliveries` | Renvoie les livraisons échouées des dernières `24h`, `3d` ou `7d` |

Le serveur propose aussi un prompt `connect_form` : des instructions pas à pas pour connecter le formulaire dans votre projet, remplies avec l'endpoint et les champs de votre formulaire quand vous passez un `form_id`.

## Que demander

- « Connectez le formulaire de contact de ce projet à Ikiform. »
- « Montrez-moi le spam de la semaine dernière sur le formulaire de liste d'attente et restaurez tout ce qui semble réel. »
- « Pourquoi mon webhook échoue-t-il ? Corrigez le handler, envoyez un test, puis renvoyez ce qui a échoué aujourd'hui. »
- « Envoie les nouvelles inscriptions à la liste d'attente vers ma route d'API /api/ikiform et mets le secret dans .env. »
- « Mets en pause l'ancien formulaire de contact et active la vérification humaine pour le nouveau. »

Les agents doivent vous demander confirmation avant de supprimer des formulaires, des soumissions ou des endpoints, de rejouer des livraisons, de publier un schéma de champs ou de modifier les domaines autorisés, les réglages anti-spam ou les limites de débit. La skill du plugin Claude Code le leur demande. Les secrets de signature et Turnstile doivent rester dans des variables d'environnement, jamais dans le code.

## Tableau de bord uniquement

Les clés API, les membres, les destinataires des notifications et la facturation restent dans le tableau de bord : une clé qui fuite ne peut donc ni créer de clés, ni inviter des personnes, ni envoyer d'e-mails à de nouvelles adresses, ni dépenser de l'argent.