# Server MCP

> Biarkan Claude Code, Cursor, VS Code, dan agen AI lain mengelola formulir, kiriman, dan webhook melalui server MCP Ikiform.

Ikiform menjalankan server [Model Context Protocol](https://modelcontextprotocol.io) jarak jauh. Hubungkan ke agen AI dan agen tersebut bisa membuat, menyambungkan, dan mengatur formulir, membaca dan memilah kiriman, serta menyiapkan dan men-debug webhook di workspace Anda, dengan secret key dan scope yang sama seperti [REST API](https://ikiform.com/id/docs/api.md).

|   |   |
| --- | --- |
| URL | `https://ikiform.com/mcp` |
| Transport | Streamable HTTP, stateless, JSON-RPC melalui `POST` |
| Autentikasi | `Authorization: Bearer ik_sk_...` |
| Rate limit | 100 request per menit per key, dibagi dengan REST API |

## Buat key

Di [dashboard](https://ikiform.com/dashboard/api-keys), buat key **secret** dan beri hanya scope yang dibutuhkan agen. Setiap tool bekerja pada workspace pemilik key. Jauhkan key dari repositori Anda: gunakan environment variable atau prompt secret dari klien Anda.

| Scope | Tool |
| --- | --- |
| `forms:read` | `list_forms`, `get_form`, dan `connect_form` dengan `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` dan `update_webhook_endpoint` (dengan `submissions:read`), `roll_webhook_secret`, `delete_webhook_endpoint`, `send_test_event`, `replay_failed_deliveries` |

> Untuk menghubungkan formulir di kode Anda, `forms:read` dan `forms:write` sudah cukup. Untuk memilah kiriman tanpa mengubah apa pun, gunakan `submissions:read`. Tool yang dipanggil tanpa scope-nya mengembalikan error `forbidden` yang menyebut scope yang kurang.

## Hubungkan klien Anda

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

**Klien lain** (`mcp.json`)

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

Di Cursor, atur `IKIFORM_API_KEY` di environment Anda. VS Code meminta key saat pertama kali dan menyimpannya dengan aman. Klien apa pun yang mendukung server HTTP jarak jauh dengan header kustom bekerja dengan cara yang sama.

Ikiform terdaftar di [MCP Registry resmi](https://registry.modelcontextprotocol.io/v0/servers?search=ikiform) sebagai `io.github.preetsuthar17/ikiform`. Di Claude Code, [plugin Ikiform](https://github.com/preetsuthar17/ikiform-plugin) menambahkan server dan skill untuk menghubungkan formulir: jalankan `claude plugin marketplace add preetsuthar17/ikiform-plugin`, lalu `claude plugin install ikiform@ikiform`.

## Tool

ID berbentuk `frm_...` untuk formulir, `sub_...` untuk kiriman, `whk_...` untuk endpoint webhook, dan `dlv_...` untuk pengiriman. Daftar mengembalikan 25 item secara default dan maksimal 100; jika `has_more` bernilai true, kirim `next_cursor` sebagai `cursor`.

| Tool | Fungsinya |
| --- | --- |
| `list_forms` | Formulir dari yang terbaru, dengan ID, nama, status, jumlah kiriman, dan endpoint |
| `get_form` | Endpoint, field, field honeypot, domain yang diizinkan, URL redirect, potongan kode, dan instruksi penyiapan sebuah formulir |
| `create_form` | Membuat formulir dari sebuah nama, dengan domain yang diizinkan dan URL redirect opsional |
| `update_form` | Menjeda atau melanjutkan formulir, dan mengubah nama, domain yang diizinkan, URL redirect, pemeriksaan spam, batas laju, atau notifikasi email |
| `set_form_fields` | Menerbitkan skema field yang menjadi acuan validasi kiriman, atau menghapusnya |
| `delete_form` | Menghapus formulir. Endpoint-nya berhenti menerima kiriman |
| `list_submissions` | Kiriman dari yang terbaru, difilter berdasarkan formulir, status (`received` atau `spam`), atau tanggal |
| `get_submission` | Satu kiriman beserta field, metadata, dan skor spam-nya |
| `mark_spam`, `mark_not_spam` | Memindahkan kiriman ke spam atau mengembalikannya, sambil mengirim webhook yang sesuai |
| `delete_submission` | Menghapus kiriman secara permanen. Tidak bisa dibatalkan |
| `list_webhook_endpoints` | Endpoint beserta URL, status, event, dan status kegagalannya. Secret tidak pernah dikembalikan |
| `create_webhook_endpoint` | Menambahkan endpoint dan mengembalikan signing secret-nya satu kali |
| `update_webhook_endpoint` | Mengubah URL, formulir, event, atau header kustom endpoint, atau mematikan dan menyalakannya |
| `roll_webhook_secret` | Mengembalikan signing secret baru. Yang lama tetap berfungsi selama 24 jam |
| `delete_webhook_endpoint` | Menghapus endpoint beserta riwayat pengirimannya |
| `list_deliveries` | Pengiriman terbaru untuk sebuah endpoint, dengan status, percobaan, dan error terakhir |
| `send_test_event` | Mengirim event `endpoint.test` bertanda tangan ke endpoint yang aktif |
| `replay_failed_deliveries` | Mengirim ulang pengiriman yang gagal dalam `24h`, `3d`, atau `7d` terakhir |

Server juga menyediakan prompt `connect_form`: instruksi langkah demi langkah untuk menghubungkan formulir di proyek Anda, diisi dengan endpoint dan field formulir Anda saat Anda mengirim `form_id`.

## Yang bisa diminta

- “Hubungkan formulir kontak di proyek ini ke Ikiform.”
- “Tunjukkan spam minggu lalu di formulir waitlist dan pulihkan yang terlihat asli.”
- “Kenapa webhook saya gagal? Perbaiki handler-nya, kirim tes, lalu kirim ulang yang gagal hari ini.”
- “Kirim pendaftar waitlist baru ke API route saya di /api/ikiform dan simpan secret di .env.”
- “Jeda formulir kontak lama dan aktifkan pemeriksaan manusia untuk yang baru.”

Agen sebaiknya meminta konfirmasi Anda sebelum menghapus formulir, kiriman, atau endpoint, memutar ulang pengiriman, menerbitkan skema field, atau mengubah domain yang diizinkan, pengaturan spam, atau batas laju. Skill plugin Claude Code menginstruksikan hal itu. Signing secret dan secret Turnstile harus disimpan di environment variable, tidak pernah di kode.

## Hanya di dashboard

Key API, anggota, penerima notifikasi, dan penagihan tetap di dashboard, sehingga key yang bocor tidak bisa membuat key, mengundang orang, mengirim email ke alamat baru, atau menghabiskan uang.