# MCP-Server

> Lass Claude Code, Cursor, VS Code und andere KI-Agenten über den MCP-Server von Ikiform Formulare, Einsendungen und Webhooks verwalten.

Ikiform betreibt einen Remote-[Model-Context-Protocol](https://modelcontextprotocol.io)-Server. Verbinde ihn mit einem KI-Agenten, und der Agent kann in deinem Workspace Formulare erstellen, verdrahten und konfigurieren, Einsendungen lesen und sichten sowie Webhooks einrichten und debuggen, mit denselben Secret Keys und Scopes wie die [REST API](https://ikiform.com/de/docs/api.md).

|   |   |
| --- | --- |
| URL | `https://ikiform.com/mcp` |
| Transport | Streamable HTTP, zustandslos, JSON-RPC über `POST` |
| Authentifizierung | `Authorization: Bearer ik_sk_...` |
| Rate-Limit | 100 Requests pro Minute und Schlüssel, geteilt mit der REST-API |

## Schlüssel erstellen

Erstelle im [Dashboard](https://ikiform.com/dashboard/api-keys) einen **Secret** Key und gib ihm nur die Scopes, die der Agent braucht. Jedes Tool arbeitet mit dem Workspace, dem der Schlüssel gehört. Halte den Schlüssel aus deinem Repository heraus: Nutze eine Umgebungsvariable oder die Secret-Abfrage deines Clients.

| Scope | Tools |
| --- | --- |
| `forms:read` | `list_forms`, `get_form` und `connect_form` mit einer `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` und `update_webhook_endpoint` (mit `submissions:read`), `roll_webhook_secret`, `delete_webhook_endpoint`, `send_test_event`, `replay_failed_deliveries` |

> Um Formulare in deinem Code anzubinden, reichen `forms:read` und `forms:write`. Zum reinen Sichten ohne Schreibzugriff nutze `submissions:read`. Ein Tool, das ohne seinen Scope aufgerufen wird, gibt einen `forbidden`-Fehler zurück, der den fehlenden Scope nennt.

## Client verbinden

**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}"
      }
    }
  }
}
```

**Andere Clients** (`mcp.json`)

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

Setze in Cursor `IKIFORM_API_KEY` in deiner Umgebung. VS Code fragt beim ersten Mal nach dem Schlüssel und speichert ihn sicher. Jeder Client, der Remote-HTTP-Server mit eigenen Headern unterstützt, funktioniert genauso.

Ikiform ist in der [offiziellen MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=ikiform) als `io.github.preetsuthar17/ikiform` eingetragen. In Claude Code fügt das [Ikiform-Plugin](https://github.com/preetsuthar17/ikiform-plugin) den Server und einen Skill zum Anbinden von Formularen hinzu: Führe `claude plugin marketplace add preetsuthar17/ikiform-plugin` aus, dann `claude plugin install ikiform@ikiform`.

## Tools

IDs sehen aus wie `frm_...` für Formulare, `sub_...` für Einsendungen, `whk_...` für Webhook-Endpunkte und `dlv_...` für Zustellungen. Listen liefern standardmäßig 25 Einträge und höchstens 100; wenn `has_more` true ist, übergib `next_cursor` als `cursor`.

| Tool | Was er macht |
| --- | --- |
| `list_forms` | Formulare, neueste zuerst, mit ID, Name, Status, Anzahl der Einsendungen und Endpunkt |
| `get_form` | Endpunkt, Felder, Honeypot-Feld, erlaubte Domains, Weiterleitungs-URL, Code-Snippets und Einrichtungsanleitung eines Formulars |
| `create_form` | Erstellt ein Formular aus einem Namen, optional mit erlaubten Domains und Weiterleitungs-URL |
| `update_form` | Pausiert oder setzt ein Formular fort und ändert seinen Namen, erlaubte Domains, die Weiterleitungs-URL, die Spamprüfung, Rate-Limits oder E-Mail-Benachrichtigungen |
| `set_form_fields` | Veröffentlicht ein Feldschema, gegen das Posts validiert werden, oder entfernt es |
| `delete_form` | Löscht ein Formular. Sein Endpunkt nimmt keine Posts mehr an |
| `list_submissions` | Einsendungen, neueste zuerst, gefiltert nach Formular, Status (`received` oder `spam`) oder Datum |
| `get_submission` | Eine Einsendung mit ihren Feldern, Metadaten und ihrem Spam-Score |
| `mark_spam`, `mark_not_spam` | Verschiebt eine Einsendung in den Spam oder zurück und sendet die passenden Webhooks |
| `delete_submission` | Löscht eine Einsendung endgültig. Kann nicht rückgängig gemacht werden |
| `list_webhook_endpoints` | Endpunkte mit URL, Status, Events und Fehlerstatus. Secrets werden nie zurückgegeben |
| `create_webhook_endpoint` | Fügt einen Endpunkt hinzu und gibt sein Signing-Secret einmalig zurück |
| `update_webhook_endpoint` | Ändert die URL, das Formular, die Ereignisse oder die eigenen Header eines Endpunkts oder schaltet ihn aus und wieder ein |
| `roll_webhook_secret` | Gibt ein neues Signing-Secret zurück. Das alte funktioniert noch 24 Stunden weiter |
| `delete_webhook_endpoint` | Löscht einen Endpunkt und seinen Zustellungsverlauf |
| `list_deliveries` | Letzte Zustellungen an einen Endpunkt, mit Status, Versuchen und dem letzten Fehler |
| `send_test_event` | Sendet ein signiertes `endpoint.test`-Event an einen aktiven Endpunkt |
| `replay_failed_deliveries` | Sendet fehlgeschlagene Zustellungen der letzten `24h`, `3d` oder `7d` erneut |

Der Server bietet außerdem einen `connect_form`-Prompt: eine Schritt-für-Schritt-Anleitung, um das Formular in deinem Projekt anzubinden, ausgefüllt mit Endpunkt und Feldern deines Formulars, wenn du eine `form_id` übergibst.

## Was du fragen kannst

- „Verbinde das Kontaktformular in diesem Projekt mit Ikiform.“
- „Zeig mir den Spam der letzten Woche im Wartelisten-Formular und stelle alles wieder her, was echt aussieht.“
- „Warum schlägt mein Webhook fehl? Korrigiere den Handler, sende einen Test und sende dann erneut, was heute fehlgeschlagen ist.“
- „Sende neue Wartelisten-Anmeldungen an meine API-Route unter /api/ikiform und lege das Secret in .env ab.“
- „Pausiere das alte Kontaktformular und schalte die Menschlichkeitsprüfung für das neue ein.“

Agenten sollten vor dem Löschen von Formularen, Einsendungen oder Endpunkten, dem erneuten Senden von Zustellungen, dem Veröffentlichen eines Feldschemas oder dem Ändern erlaubter Domains, Spam-Einstellungen oder Rate-Limits bei dir nachfragen. Der Skill des Claude-Code-Plugins weist sie dazu an. Signing- und Turnstile-Secrets gehören in Umgebungsvariablen, nie in den Code.

## Nur im Dashboard

API-Schlüssel, Mitglieder, Benachrichtigungsempfänger und die Abrechnung bleiben im Dashboard, sodass ein geleakter Schlüssel keine Schlüssel erstellen, niemanden einladen, keine E-Mails an neue Adressen senden und kein Geld ausgeben kann.