# MCP サーバー

> Claude Code、Cursor、VS Code などの AI エージェントから、Ikiform の MCP サーバー経由でフォーム、送信データ、Webhook を管理できます。

Ikiform はリモートの [Model Context Protocol](https://modelcontextprotocol.io) サーバーを提供しています。AI エージェントに接続すると、エージェントがワークスペースのフォームの作成、配線、設定、送信データの読み取りと仕分け、Webhook のセットアップとデバッグを、[REST API](https://ikiform.com/ja/docs/api.md) と同じシークレットキーとスコープで行えます。

|   |   |
| --- | --- |
| URL | `https://ikiform.com/mcp` |
| トランスポート | Streamable HTTP、ステートレス、`POST` による JSON-RPC |
| 認証 | `Authorization: Bearer ik_sk_...` |
| レート制限 | キーごとに 1 分あたり 100 リクエスト。REST API と共有 |

## キーを作成する

[ダッシュボード](https://ikiform.com/dashboard/api-keys)で **シークレット** キーを作成し、エージェントに必要なスコープだけを付与します。どのツールも、キーを所有するワークスペースに対して動作します。キーはリポジトリに含めず、環境変数かクライアントのシークレット入力を使ってください。

| スコープ | ツール |
| --- | --- |
| `forms:read` | `list_forms`、`get_form`、`form_id` を指定した `connect_form` |
| `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` と `update_webhook_endpoint`（`submissions:read` も必要）、`roll_webhook_secret`、`delete_webhook_endpoint`、`send_test_event`、`replay_failed_deliveries` |

> コードでフォームを接続するだけなら、`forms:read` と `forms:write` で足ります。読み取り専用で仕分けるなら `submissions:read` を使います。必要なスコープなしでツールを呼び出すと、不足しているスコープを示す `forbidden` エラーが返ります。

## クライアントを接続する

**Claude Code** (`ターミナル`)

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

**その他のクライアント** (`mcp.json`)

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

Cursor では、環境変数 `IKIFORM_API_KEY` を設定します。VS Code は初回にキーを尋ね、安全に保存します。カスタムヘッダー付きのリモート HTTP サーバーに対応したクライアントなら、どれも同じ方法で使えます。

Ikiform は[公式 MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=ikiform) に `io.github.preetsuthar17/ikiform` として登録されています。Claude Code では、[Ikiform プラグイン](https://github.com/preetsuthar17/ikiform-plugin)でサーバーとフォーム接続用のスキルを追加できます。`claude plugin marketplace add preetsuthar17/ikiform-plugin` を実行し、続けて `claude plugin install ikiform@ikiform` を実行してください。

## ツール

ID の形式は、フォームが `frm_...`、送信データが `sub_...`、Webhook エンドポイントが `whk_...`、配信が `dlv_...` です。一覧はデフォルトで 25 件、最大 100 件を返します。`has_more` が true のときは、`next_cursor` を `cursor` として渡してください。

| ツール | できること |
| --- | --- |
| `list_forms` | フォームを新しい順に一覧。ID、名前、ステータス、送信数、エンドポイント付き |
| `get_form` | フォームのエンドポイント、フィールド、ハニーポットのフィールド、許可ドメイン、リダイレクト URL、コードスニペット、設定手順 |
| `create_form` | 名前からフォームを作成。許可ドメインとリダイレクト URL は任意 |
| `update_form` | フォームの一時停止と再開、名前、許可ドメイン、リダイレクト URL、スパムチェック、レート制限、メール通知の変更 |
| `set_form_fields` | 送信データのバリデーションに使うフィールドスキーマの公開、または削除 |
| `delete_form` | フォームを削除。エンドポイントは送信を受け付けなくなります |
| `list_submissions` | 送信データを新しい順に一覧。フォーム、ステータス（`received` または `spam`）、日付で絞り込み可能 |
| `get_submission` | 1 件の送信データと、そのフィールド、メタデータ、スパムスコア |
| `mark_spam`, `mark_not_spam` | 送信データをスパムに移す、またはスパムから戻す。対応する Webhook も送信 |
| `delete_submission` | 送信データを完全に削除。元に戻せません |
| `list_webhook_endpoints` | エンドポイントの URL、ステータス、イベント、失敗状態。シークレットは返しません |
| `create_webhook_endpoint` | エンドポイントを追加し、署名シークレットを 1 回だけ返します |
| `update_webhook_endpoint` | エンドポイントの URL、フォーム、イベント、カスタムヘッダーの変更、またはオンとオフの切り替え |
| `roll_webhook_secret` | 新しい署名シークレットを返します。古いものは 24 時間使えます |
| `delete_webhook_endpoint` | エンドポイントとその配信履歴を削除 |
| `list_deliveries` | エンドポイントの最近の配信。ステータス、試行回数、最後のエラー付き |
| `send_test_event` | 有効なエンドポイントに、署名付きの `endpoint.test` イベントを送信 |
| `replay_failed_deliveries` | 直近 `24h`、`3d`、`7d` に失敗した配信を再送 |

サーバーは `connect_form` プロンプトも提供しています。プロジェクトにフォームを接続する手順で、`form_id` を渡すとフォームのエンドポイントとフィールドが埋め込まれます。

## 頼めること

- 「このプロジェクトのお問い合わせフォームを Ikiform に接続して」
- 「ウェイトリストフォームの先週のスパムを見せて。本物らしいものは元に戻して」
- 「Webhook が失敗するのはなぜ？ハンドラーを直して、テストを送ってから、今日失敗した分を再送して」
- 「新しいウェイトリストの登録を /api/ikiform の API ルートに送って、シークレットは .env に入れて」
- 「古いお問い合わせフォームを一時停止して、新しいほうで人間確認をオンにして」

フォームや送信データ、エンドポイントの削除、配信の再送、フィールドスキーマの公開、許可ドメイン、スパム設定、レート制限の変更の前には、エージェントがあなたに確認するべきです。Claude Code プラグインのスキルは、そうするよう指示しています。署名シークレットと Turnstile シークレットは、コードではなく環境変数に入れてください。

## ダッシュボードのみ

API キー、メンバー、通知の宛先、請求はダッシュボードで管理します。そのため、キーが漏えいしても、キーの作成、人の招待、新しいアドレスへのメール送信、お金の使用はできません。