formbase

Formstep MCP サーバー

Formstep のホスト型 MCP サーバーです。1 回のリクエストで、確認済みの顧客情報を収集できます。

エージェントは、1 人の顧客である宛先にリクエストを送信します。ブランドと宛先の言語に合わせたフォームに、把握している情報をあらかじめ入力しておくため、宛先は確認または修正するだけです。宛先はアカウントを作成せずに、同じページでファイルをアップロードし、署名し、予約し、または支払いができます。回答はフィールドキーに紐づけて返され、外部 ID に加え、フォームに判断を求める質問がある場合は、承認、却下、または変更依頼の結果も返されます。エージェントは request_get で回答を読み取るか、宛先が送信した瞬間に Formstep がコールバック URL を呼び出します。

サーバーの URL は次のとおりです。

https://api.formstep.io/api/mcp

このリポジトリには、ドキュメント、設定例、Grok Build プラグインマニフェストが含まれています。インストールや実行は不要です。

• エージェントにできること
• AI ツールを接続する
• 試してみる
• ツール
• 制限
• プロトコルの詳細
• ドキュメント
• 問題を報告する

エージェントにできること

• リクエストを送信する。 名前を指定した 1 人に情報を尋ねます。回答を事前入力したり、編集できないようにしたりでき、相手の回答を読み取れます。公開済みのフォームを使うか、同じ呼び出しでエージェントにフォームを作成させることもできます。
• フォームを作成する。 フォームを作成し、質問、ページ、ロジックを追加、編集、削除します。
• 公開して共有する。 フォームを公開し、共有リンクを作成し、翻訳し、テーマと設定を指定します。
• 結果を読み取る。 フォームの回答一覧を取得し、分析情報を読み取ります。

ほとんどの AI ツールは OAuth で Formstep にサインインします。URL を貼り付け、ブラウザーで Formstep にサインインして、ワークスペースを選択します。スクリプトやヘッドレスエージェントは、代わりに API トークンを送信します。

AI ツールを接続する

クライアント ID、シークレット、トークンの入力欄は空のままにしてください。AI ツールはサーバーから Formstep のサインインページを見つけ、自身を登録します。

Claude Code

claude mcp add --transport http formstep https://api.formstep.io/api/mcp

その後、Claude Code で /mcp と入力してサインインします。

プロジェクトで作業する全員がサーバーを共有できるようにするには、代わりに .mcp.json をプロジェクトにコミットします。

{
  "mcpServers": {
    "formstep": {
      "type": "http",
      "url": "https://api.formstep.io/api/mcp"
    }
  }
}

Claude desktop と claude.ai

Customize › Connectors › + › Add custom connector を開き、URL を貼り付けます。claude.ai で追加したコネクターは、デスクトップアプリとモバイルアプリでも使えます。

Team および Enterprise では、オーナーが Organization settings › Connectors で先にコネクターを追加します。その後、メンバーはコネクターの Connect をクリックします。Free では、カスタムコネクターを 1 つ追加できます。Claude の公式ガイド：カスタムコネクターを始める。

ChatGPT

Settings › Apps › Advanced settings で開発者モードを有効にします。次に Settings › Apps › Create を開き、URL を貼り付けて OAuth を選択し、Scan Tools をクリックして Formstep にサインインし、Create をクリックします。

開発者モードはウェブ版でのみ利用できます。Pro では、ChatGPT は読み取りのみ可能です。リクエストの送信やフォームの編集など、変更を伴うツールを使うには Business、Enterprise、または Edu が必要です。Business では、開発者モードを使用できるのは管理者とオーナーのみです。OpenAI の公式ガイド：ChatGPT の開発者モードと MCP アプリ。

Cursor

プロジェクトの .cursor/mcp.json に追加するか、すべてのプロジェクトで使う場合は ~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "formstep": {
      "url": "https://api.formstep.io/api/mcp"
    }
  }
}

Cline

Cline は API トークンで接続します（作成方法は以下を参照してください）。Cline の cline_mcp_settings.json に次の内容を追加します。

{
  "mcpServers": {
    "formstep": {
      "type": "streamableHttp",
      "url": "https://api.formstep.io/api/mcp",
      "headers": {
        "Authorization": "Bearer fs_YOUR_TOKEN"
      }
    }
  }
}

または、Cline にインストールを依頼できます。llms-install.md に、Cline が実行する手順が記載されています。

Grok Build

このリポジトリは Grok Build プラグインでもあります。 .grok-plugin/plugin.json、.mcp.json サーバー設定、そして 1 つのスキル formstep-requests が含まれています。このプラグインはお使いのマシン上で何も実行しません。ネットワークエンドポイント https://api.formstep.io/api/mcp を 1 つ呼び出し、Formstep OAuth、またはヘッダーに追加した API トークンでサインインします。

その他のツール

サインインに対応したリモート MCP サーバーをサポートするツールであれば、同じように使えます。URL でサーバーを追加する方法を確認してください。接続ガイド から、各ツール独自の手順を確認できます。

サインインしてワークスペースを選択する

エージェントが初めて Formstep を使用するとき、AI ツールによってブラウザーで Formstep のページが開きます。サインインし、ワークスペースを選択して、Authorize をクリックしてください。

接続できるのは、そのワークスペース 1 つだけです。別のワークスペースを使うには、Formstep をもう一度追加して、もう一方のワークスペースを選択してください。

動作を確認するには、次のように尋ねてください。

List my Formstep forms and whether each one is published.

接続を解除するには、Formstep ワークスペースのサイドバーで OAuth and API Keys を開きます。Connected apps の下にある接続の横のゴミ箱アイコンをクリックし、Disconnect をクリックして確定してください。

スクリプトとヘッドレスエージェント：API トークンを使用する

スクリプト、CI ジョブ、ヘッドレスエージェントなど、ブラウザーを開けないものは、代わりに API トークンをヘッダーとして送信します。

1. ワークスペースのサイドバーで OAuth and API Keys を開き、Create token をクリックします（API トークン）。
2. トークンをコピーします。fs_ で始まります。
3. Authorization: Bearer ヘッダーとして送信します。

OAuth 接続と同様に、トークンがアクセスできるのは 1 つのワークスペースだけです。作成から 30 日後に有効期限が切れ、延長できないため、交換の予定を立ててください。git には含めないでください。

コマンドラインから Claude Code を使う場合：

claude mcp add --transport http formstep https://api.formstep.io/api/mcp \
  --header "Authorization: Bearer fs_YOUR_TOKEN"

または、設定ファイルに記述します。これは Claude Code 用の .mcp.json です。Cursor でも同じ headers オブジェクトを mcp.json で使用します。

{
  "mcpServers": {
    "formstep": {
      "type": "http",
      "url": "https://api.formstep.io/api/mcp",
      "headers": {
        "Authorization": "Bearer fs_YOUR_TOKEN"
      }
    }
  }
}

その他のツールでも同じ URL とヘッダーを使います。設定方法については、それぞれのドキュメントを参照してください。

試してみる

公開済みのフォームの名前を使って、1 人にリクエストを送信します。

Send a Formstep request with the "Supplier onboarding" form to Ada Lovelace ([email protected]). Fill in the company name "Analytical Engines Ltd" and lock it so it cannot be changed. Use supplier-2041 as the external ID. Don't send the invitation email; give me the link and I will send it myself.

エージェントは fields_list でフォームのフィールドキーを読み取り、request_create でリクエストを作成して、リクエストのリンクを返します。

まだフォームがありませんか？エージェントは同じ呼び出しでフォームを作成することもできます。

Ask Ada Lovelace ([email protected]) for her last three payslips and a 40 EUR processing fee, and let her book a 15 minute call. Use our logo at https://acme.example/logo.png and a dark blue cover. Give me the link.

エージェントは workspaceConnection_list でワークスペースの Stripe と Cal.com の接続を確認し、formId の代わりに form オブジェクトを指定して request_create を呼び出します。このオブジェクトには、名前、ブロック、指定したロゴとカバーが含まれます。Formstep はフォームを作成して公開し、1 回の操作でリクエストも作成します。また、回答が返される際に使われるフィールドキーも返します。同じ定義を再度使うとフォームが再利用されるため、100 件のリクエストを送ってもフォームは 1 つだけです。

フォームで Send reminders が有効になっている場合、Formstep はスケジュールされたリマインダーを引き続き受信者にメールで送信します。これを防ぐには、リマインダーなし とも伝えてください。

エージェントには受信者が送信したことが通知されないため、後で尋ねてください。

Has the Formstep request supplier-2041 been answered? Show me the answers.

エージェントは request_list で外部 ID を使ってリクエストを見つけ、request_get で読み取ります。リクエストが完了すると、回答はフィールドキーをキーとして返されます。

手順の詳細：AI エージェントでリクエストを送信する、1 回の呼び出しでフォームとリクエストを作成する、AI エージェントでフォームを作成する。

ツール

AI ツールが接続すると、すべてのツールが完全な入力スキーマとともに tools/list に表示されます。MCP サーバーのリファレンス で詳しく説明しています。

リクエスト

名前を指定した1人に情報を依頼し、結果を読み取ります。

• fields_list：公開済みフォームでリクエストの対象にできるフィールドキーを一覧表示します。formIdを指定してrequest_createを呼び出す前に実行してください。
• request_create：事前入力、ロックされたフィールド、コンテキスト、配信、期限、任意のコールバックを設定して、フォームを1人の宛先に割り当てます。公開済みフォームにはformIdを指定するか、同じ呼び出し内でフォームを作成するにはformを指定します（以下を参照）。
• request_get：IDで1件のリクエストを読み取ります。ステータス、タイムライン、完了後はフィールドキーに対応付けられた回答を返します。
• request_list：フォームまたはワークスペースのリクエストを、ステータス、結果、または独自の外部IDで絞り込んで一覧表示します。
• request_cancel：保留中のリクエストを取り消します。
• request_remind：宛先にリマインダーメールを今すぐ送信します。
• request_replayCallback：コールバックがエンドポイントに届かなかった場合、再送信します。
• document_create：リクエストで宛先にファイルを渡すためのアップロードを予約します。1件のアップロードは、任意の数のリクエストに使用できます。
• workspaceConnection_list：ワークスペースに接続済みのStripeおよびCal.comアカウントと、未接続のアカウントを接続するためのconnectUrlを表示します。支払いまたは予約を含むフォームを作成する前に実行してください。
• scheduler_listEventTypes：予約ブロックで指定できるCal.comのイベントタイプと、それぞれをフォームから予約できるかどうかを表示します。
• paymentConnection_setDefault：支払いの請求にデフォルトで使用するStripeアカウントを選択します。ワークスペースの所有者のみが実行できます。

リクエスト内で作成するフォーム

request_createでは、formIdの代わりにformを指定できます。Formstepは通常のフォームを作成して公開し、リクエストを1回の操作で作成します。両方とも作成されるか、どちらも作成されないかのいずれかです。エージェントにエディターツールやfields_listの呼び出しは不要です。

{
  "form": {
    "name": "Documents and fee for your mortgage application",
    "logo": { "type": "image", "url": "https://acme.example/logo.png" },
    "cover": { "type": "color", "color": "#0f4c81" },
    "blocks": [
      { "type": "paragraph", "content": "Hi {{first_name}}, upload the documents and pay the fee." },
      { "type": "hiddenField", "key": "first_name" },
      { "type": "file", "key": "payslips", "title": "Your last three payslips", "maxFiles": 3 },
      { "type": "payment", "key": "fee", "title": "Processing fee", "amount": 40, "currency": "EUR" },
      { "type": "scheduleAppointment", "key": "call", "title": "Pick a time", "eventType": "15 min call" }
    ]
  },
  "recipient": { "email": "[email protected]", "name": "Ada" },
  "context": { "first_name": "Ada" }
}

• **form**にはnameとblocks（フォーム内の順序で1～200個）を指定します。また、任意でlanguage、ブランド（logo、cover、emoji）、theme（カラーモードごとのプリセットID）、settings、translations（追加言語でのフォーム内のすべての文字列）も指定できます。Formstepは各画像URLを1回取得し、独自のコピーを保持します。画像は公開されているJPEG、PNG、またはWebPである必要があります。
• ブロックには、対応するeditor_insert*ツールのパラメーターからformIdとafterを除いたものに加え、keyを指定します。質問、ドキュメント、支払い、scheduleAppointment、decision、コンテンツブロック、行、ページ区切り、繰り返しグループ、非表示フィールド、計算フィールド、他のブロックをキーで参照するロジックルールなど、すべてのブロックタイプを使用できます。
• レスポンスにはform: { id, name, reused, fields }が追加されます。fieldsは回答が返される際に使用されるキーです。
• 1つの定義につきフォームは1つです。 同じformを再度指定すると、公開済みフォームが再利用されます（reused: true）。顧客名、請求書番号、金額はname、ブロック、ブランドではなく、prefillとcontextに指定してください。そうしないと、呼び出しごとに新しいフォームが作成されます。エージェントはブランドを保持し、すべてのリクエストで変更せずに送信します。すべての質問にkeyを設定してください。
• 支払いと予約には、ワークスペースにStripeまたはCal.comを接続する必要があります。workspaceConnection_listで接続済みのアカウントを確認でき、一度だけユーザーが開くconnectUrlが返されます。エージェント自身がアカウントを接続することはできません。

完全なリファレンスはload_skill("requests")のセクション2c、および1回の呼び出しでフォームとリクエストを作成するを参照してください。

フォーム

• form_list、form_get、form_create、form_update：フォームの検索、読み取り、作成、名前の変更を行い、フォルダー、絵文字、カバー、ロゴを設定します。
• form_publish、form_unpublish：回答の受付を開始または停止します。form_publishは2回呼び出しても安全です。
• form_delete、form_restore：フォームをゴミ箱に移動します。これにより共有リンクも無効になります。また、フォームを復元します。

form_getは、最後に公開されたバージョンの質問を返します。下書きの内容を読み取るには、editor_getDocumentを使用してください。

エディター

• editor_getDocument：フォームの構造全体を読み取ります。
• editor_updateElement、editor_deleteElement：ブロックを編集、移動、または削除します。
• editor_formatText：ブロック内のテキストを整形します。
• editor_setLogic、editor_testLogic：ロジックブロックのルールを変更してテストします。ブロックは editor_insertLogic で作成します。

ブロックの種類ごとに、正確なスキーマを持つ専用の挿入ツールがあります。

• 質問： editor_insertTextQuestion、editor_insertContactQuestion、editor_insertNumberQuestion、editor_insertDateQuestion、editor_insertTimeQuestion、editor_insertRadioQuestion、editor_insertCheckboxQuestion、editor_insertSelectQuestion、editor_insertPictureChoiceQuestion、editor_insertSwitchQuestion、editor_insertRatingQuestion、editor_insertLinearScaleQuestion、editor_insertRankingQuestion、editor_insertMatrixQuestion、editor_insertFileQuestion、editor_insertSignatureQuestion、editor_insertPaymentQuestion、editor_insertScheduleAppointmentQuestion
• 決定： editor_insertDecisionQuestion は、回答がリクエストの結果となる承認／却下／変更の選択肢を挿入します。手動で作成したラジオボタンの質問では、そのような結果は生成されません。
• コンテンツ： editor_insertHeader、editor_insertParagraph、editor_insertImage、editor_insertList、editor_insertTable、editor_insertRow、editor_insertEmbedded、editor_insertPageDivider、editor_insertDocumentsBlock
• データとロジック： editor_insertHiddenField、editor_insertCalculatedField、editor_insertVariable、editor_insertRepeatingGroup、editor_insertLogic

共有と結果

• formShareLink_list、formShareLink_create、formShareLink_update：カスタムドメイン上のものも含め、共有リンクを管理します。
• formSubmission_list：フォームの送信済み回答を一覧表示します。リクエストに応じて下書きも表示できます。
• formWebhook_list、formWebhook_create、formWebhook_update、formWebhook_delete、formWebhook_test：フォームのすべての回答を、ウェブフック専用のシークレットで署名してエンドポイントに POST します。
• formAnalytics_get：デバイス、国、ブラウザー、流入元別の表示数、送信数、完了率、ユニーク訪問者数を取得します。

外観、設定、翻訳

• formTheme_get、formTheme_set：ライトテーマとダークテーマを設定します。
• formSettings_get、formSettings_update：通知メール、完了後のリダイレクト、パスワード、保持期間、言語を管理します。
• translationLanguage_list、translationDraft_get、translationDraft_update、translationDraft_publish、translationLanguage_delete：フォームを下書きとして翻訳し、その後公開します。

ワークスペース

• workspace_list：接続先となる1つのワークスペースと、その ID を取得します。
• workspaceFolder_list、workspaceFolder_create、workspaceFolder_update、workspaceFolder_delete：フォルダーを管理します。

組み込みガイド

2つのツールは処理を実行するのではなく、ドキュメントを返します。

• load_skill は、requests、question-types、logic-rules、editing-flows、form-best-practices、form-themes、form-settings、analytics、toon-format のいずれかのトピックに関するガイドを読み込みます。
• load_tools は、ツールのグループ（カタログ）の使用方法に関するメモを読み込みます。カタログは、request-lifecycle（リクエスト、ドキュメント、Stripe および Cal.com の接続）、editor-inserts、editor-actions、form-lifecycle、form-appearance、form-behavior、form-sharing、form-translations、form-data、workspace-management です。

各ガイドとカタログは、skill://<name>（例：skill://requests）の MCP リソースとしても提供されます。また、サーバーは identity、capabilities、data_tools、editor_tools の4つのプロンプトも提供します。

事前確認が必要なツール

7 つのツールは破壊的としてマークされています。元に戻すには別の呼び出しが必要、または元に戻せないためです：form_delete、form_unpublish、workspaceFolder_delete、editor_deleteElement、translationLanguage_delete、formWebhook_delete、request_cancel。ほとんどの AI ツールは実行前に確認を求めます。確認はお使いの AI ツールが行うため、実行を確実に止める必要がある場合は、承認設定を確認してください。

元に戻せない操作が 2 つあります：

• workspaceFolder_delete は、フォルダーとそのサブフォルダー、およびフォルダー内のすべてのフォームを完全に削除します。
• revoked: true を指定した formShareLink_update は、共有リンクを完全に無効にします。このツールは破壊的としてマークされていないため、お使いの AI ツールが事前確認を求めない場合があります。

制限

• レート制限。 トークンごとに、REST API と共有で 1 分あたり 120 回のツール呼び出しが可能です。カウントされるのは tools/call のみです。上限を超えると、呼び出しは RATE_LIMITED と retryAfterMs を含むツール実行失敗の結果を返します。request_create と document_create には、トークンごとに 1 分あたり 60 回の別の制限も適用されます。
• 1 日あたりの新規フォーム数。 ワークスペースで form を指定した request_create により作成できる新規フォームは、1 日あたり最大 300 件です。上限に達すると、新規フォームを作成する呼び出しは RATE_LIMITED で失敗しますが、既存のフォームを再利用する呼び出しは引き続き使用できます。
• 月間利用枠。 request_create を実行するたびに、受信者が回答するかどうかにかかわらず、ワークスペース所有者のプランの月間利用枠を 1 単位消費します。テストリクエスト（test: true）では消費されません。利用枠を使い切ると、request_create は MONTHLY_ALLOWANCE_REACHED で失敗します。
• 有料プラン。 受信者へのメール送信（招待とリマインダー）および formAnalytics_get の利用には、Pro または Business プランが必要です。プランと料金をご覧ください。
• 受信者の送信時に通知されません。 サーバーからエージェントに呼び出しが行われることはありません。後で再度確認するか、request_create に callbackUrl を渡して、Formstep からエンドポイントを呼び出すようにしてください（コールバック）。
• ツール呼び出しによるファイルのアップロードはできません。 画像は URL で設定します。URL は http(s):// URL または data:image URI です。リクエスト用のドキュメントは例外です。document_create が返すアップロード URL に、1 時間以内にファイルを PUT してください。PDF と画像のみ対応しており、1 ファイルあたり 25 MB までです。
• ワークスペースの AI スキルは利用できません。 Formstep で作成したスキルは、Formstep に組み込まれた AI チャットでのみ動作します。サーバー独自のガイド（load_skill）は MCP 経由で利用できます。

プロトコルの詳細

独自の MCP クライアントを作成する方や、接続をデバッグする方に向けた情報です。

• トランスポート。 Streamable HTTP で、POST のみを使用します。すべてのレスポンスは JSON です。イベントストリームもセッション ID もないため、各呼び出しは個別に完結します。MCP の仕様で定められているとおり、Content-Type: application/json と Accept: application/json, text/event-stream を送信してください。
• プロトコルバージョン。 2025-11-25。
• サインイン。 initialize を含むすべての呼び出しに Authorization: Bearer <token> が必要です。指定しない場合、サーバーは https://api.formstep.io/.well-known/oauth-protected-resource を示す WWW-Authenticate ヘッダーとともに 401 を返します。クライアントはそこから OAuth 2.1 サーバーを見つけます。このサーバーでは PKCE（S256）が必須で、動的クライアント登録をサポートしています。リファレンスに各手順が記載されています。
• トークン。 どちらの種類も同じワークスペースとツールを利用できます。
  • API トークンは fs_ で始まり、作成から 30 日間有効です。
  • OAuth アクセストークンは fso_ で始まり、1 時間有効です。AI ツールはリフレッシュトークンを使って更新します。リフレッシュトークンは 30 日間有効で、使用するたびに新しいものに置き換わります。
• 結果。 ツールの結果は JSON を含む 1 つのテキスト項目です。失敗の場合は success: false と error メッセージが返されます。リクエストツールは、details に UNKNOWN_FIELD_KEY などの理由コードと、呼び出しの修正方法を示す suggestion を追加します。よくある理由コードについては、リクエストのトラブルシューティングをご覧ください。
• ブラウザー。 サーバーは Formstep 自身のサイトからのクロスオリジン呼び出しのみを許可しているため、別のオリジンにあるウェブページから直接呼び出すことはできません。

ドキュメント

• MCP サーバーのリファレンス：すべてのツール、独自クライアント向けの OAuth、制限
• AI エージェントを接続する
• AI エージェントでフォームを作成する
• AI エージェントでリクエストを送信する
• リクエストの概要、フィールドキー、コールバック
• 1 回の呼び出しでフォームとリクエストを作成する
• API トークンとREST API
• プライバシーポリシーと利用規約

問題を報告する

• [email protected] にメールを送信してください。
• または、このリポジトリでイシューを作成してください。使用している AI ツール、サインイン方法、呼び出したツール、返されたエラーを記載してください。

イシューは公開されます。トークン（fs_... または fso_...）や、回答者の回答を貼り付けないでください。その場合はメールでお問い合わせください。セキュリティ上の問題を報告するには、SECURITY.mdをご覧ください。

このドキュメントへの修正は、プルリクエストで歓迎します。

ライセンス

このリポジトリ内のファイルは MIT ライセンスで提供されています。詳細はLICENSEをご覧ください。Formstep サービスの利用には利用規約が適用されます。