MCP サーバー

Crisphive の公式 MCP サーバーです。Claude、ChatGPT、Cursor、あるいは任意の MCP クライアントを Crisphive に向けるだけで、フィールドサービス事業の顧客管理、サービスカタログの閲覧、実際の予約空き状況の確認、そしてジョブの予約ができます — Developer API のすべての REST エンドポイントが、ツールとして公開されています。

https://api.crisphive.com/mcp

まず試してみる

接続したら（chsk_test_ のサンドボックスキーで十分です）、以下のプロンプトをそのままエージェントに貼り付けてください。同じプロンプトがすべての Crisphive リスティングに掲載されており、どこでも同じファーストラン体験になります（プロンプト自体は英語のままです）：

• ジョブ作成 — “Schedule a 2-hour HVAC job at 145 Laurier Ave W tomorrow for Marie Tremblay, 613-555-0142.” createCustomer → listJobRequestBookingWindows → createJobRequest → quoteJobRequest → confirmJobRequest
• 緊急ジョブの挿入 — “Emergency plumbing job now at 99 Bank St for David Okafor (613-555-0198) — show me what gets rescheduled.” listEmergencyCandidates → previewEmergencyReschedule → commitEmergencyReschedule
• 一日のアウトライン — “Outline my day tomorrow and flag anything at risk.” listJobRequests → getTechnicianSchedule
• 空き時間の発見 — “Find 3 hours this week for a bike ride with my wife without risking any jobs.” getTechnicianSchedule → エージェントがスケジュールの余裕から推論します

同じ依頼を、あなたの言葉で

エンジンは誰が話しているかを気にしません — ディスパッチャーもオーナーも開発者も同じツールを操作します。同じ依頼を、それぞれの役割が実際に打ち込みそうな言い方で並べました（プロンプト自体は英語のままです）：

仕組み

上記のどのプロンプトも同じ経路をたどります。Claude が自然言語をツール呼び出しに変換し、MCP サーバーが他のクライアントと同じ公開 REST API を操作し、決定論的ソルバーがスケジュールを計算します — 最適化コアに LLM は一切含まれません。結果はビジネスの基幹記録システムに同期されます。

要件

Streamable HTTP 経由のリモートサーバーに対応し、カスタムヘッダーを送信できる MCP クライアントであれば何でも — claude.ai、Claude Desktop、Claude Code、ChatGPT、Gemini CLI、Cursor、VS Code、Windsurf、Cline、Zed、LM Studio など。トランスポートはステートレス（プレーンな JSON レスポンス — SSE もセッションもなし）で、サーバーはツールのみを公開します。

インストール

以下からクライアントを選び、正確な接続方法をご確認ください:

# OAuth — you'll be prompted to authorize in the browser
claude mcp add --transport http crisphive https://api.crisphive.com/mcp

# …or pass an API key to skip the browser step
claude mcp add --transport http crisphive https://api.crisphive.com/mcp \
  --header "Authorization: Bearer chsk_test_YOUR_KEY"

認証

リクエストは、ベアラートークンとして送信されるシークレット API キーで認証されます — REST /v1 API と同じキーです。キーは Crisphive のビジネスダッシュボードから作成します。キーのプレフィックスが、エージェントの扱うデータを選択します:

• chsk_live_… → ライブ（本番）データ。
• chsk_test_… → サンドボックス（分離されたテスト）データ。テストキーを持つエージェントはサンドボックスデータにしかアクセスできません — エージェントに安心して試させるための推奨方法です。

キーはサーバー側で保持し、環境から読み込んでください — 決してコミットしたり、chsk_ キーをクライアントサイドのアプリに同梱したりしないでください。

OAuth 2.1（API キー不要）

claude.ai / ChatGPT コネクタ、あるいはユーザーが自分の Crisphive ビジネスを持ち込むようなプロダクトを構築していますか？ /mcp エンドポイントは、完全な OAuth 2.1 認可サーバーでもあります: ビジネスオーナーが同意画面でエージェントを認可し、キーが一切コピーされることはありません。準拠した MCP クライアントはフロー全体を自動的に実行し（通常、OAuth コードを書く必要はありません）、WWW-Authenticate: Bearer resource_metadata="…" を伴う 401 によってトリガーされます:

それ以降は、Authorization: Bearer <access_token> を付けて /mcp を呼び出します — API キーの場合とまったく同じです。トークンは同意したオーナーのビジネス、リージョン、環境に紐付けられるため、エージェントが別のテナントに到達したり、ライブ↔サンドボックスを切り替えたりすることは決してできません。エージェントはそれを承認した本人として動作します — そのメンバーがダッシュボードでできる以上のことをすることはなく、その人が削除または一時停止されると機能しなくなります。さらに制限するには、より狭い scope（スペース区切りの権限コード、例: customers_view job_view）をリクエストしてください。省略すると、そのメンバーが行えるすべての操作が対象になります。アクセストークンの有効期間は約 1 時間です — 接続を維持するにはリフレッシュトークンを使用してください。同じトークンは REST /v1 API でも使えます — マルチテナント連携を構築するを参照してください。

接続の有効期間

MCP 接続は 2 つの独立したクロックによって管理されます。日常的に使われているエージェントがスケジュールで切断されることはなく、放置されたエージェントは自然に期限切れになります。

• アイドルウィンドウ — 30 日。トークンをリフレッシュするたびに、さらに 30 日間有効な新しいリフレッシュトークンが発行されます。接続を使い続ければ無期限に延長され、30 日間使わなければ失効します。
• 絶対上限 — 90 日。アクティビティにかかわらず、接続はビジネスオーナーが承認してから 90 日後に終了します。ビジネスは Developers → MCP connections から接続ごとに 1 日から 365 日までの任意の値を設定できます。カウントダウンは変更時ではなく、最初の承認時から計測されます。

いずれかのクロックが切れるとリフレッシュは失敗し、オーナーが同意画面からアプリを再承認する必要があります。リフレッシュの失敗は常に「認可フローのやり直し」として扱い、リトライ可能なエラーとして扱わないでください。接続の有効期限の 14 日前に、ビジネスのオーナーと管理者にメールが送信されます — 再承認にはオーナーがブラウザで操作する必要があるため、警告はキーの場合よりも早く届きます。

ツール

公開 /v1 API の操作ごとに 1 つ、合計 46 個のツールがあります — 名前は SDK のメソッド（listCustomers、createJobRequest など）と同じで、同一の OpenAPI 仕様から生成されるため、REST と MCP がずれることはありません。パス／クエリパラメータとリクエストボディのフィールドは、ツールごとに単一の引数オブジェクトへフラット化されます。

• すべてのツールは、生の REST エンベロープ — { error_code, message, data } — をテキストとして返します。エージェントは成功時に data を取り出し、失敗時に error_code を読み取ります。
• 制限付きキーはそのまま適用されます: customers_view にスコープされたキーは、書き込み系ツールから 403 を受け取ります。
• 作成系ツール（createCustomer、createJobRequest）はオプションの idempotency_key を受け付け、Idempotency-Key ヘッダーとして転送されます — リトライ時に同じ値を渡せば、再試行が重複を作ることはありません。
• ヘッダー入力も引数です: 例えば listJobRequestBookingWindows は x_timezone（IANA タイムゾーン。X-Timezone ヘッダーとして送信）を受け付けます。
• すべてのツールは outputSchema を宣言し、テキストと併せて structuredContent（パース済みのエンベロープ）を返すため、型付きクライアントは再パースを省略できます。
• 動作ヒントはツールごとに設定されます — 読み取りには readOnlyHint、削除には destructiveHint が付くため、Claude のようなクライアントは破壊的な操作を実行する前に確認できます。

典型的なエージェントのフローは次のようになります:

listSkills / listJobTypes                → discover reference IDs
createCustomer                           → { customer_id }
listJobRequestBookingWindows             → offer only the returned windows
createJobRequest                         → booking created
getJobRequest / listJobRequestChanges    → track status

ページネーション

リスト系ツールは page / limit を受け付け、meta オブジェクト（per_page、current_page、total_pages）を返すため、エージェントは大きな結果セットを 1 ページずつ辿れます。

レート制限

リクエストはキーごとにレート制限され、REST と共有されます: 1 分あたり 240 件。429 エンベロープを受け取ったら、バックオフしてリトライしてください。

エラー

すべてのツールは Crisphive のレスポンスエンベロープを返します（テキストとして、また structuredContent として）: error_code は成功時に 0、失敗時には安定した文字列（CUSTOMER_NOT_FOUND、API_KEY_INVALID など）になります。メッセージ文ではなく、常にコードで判定してください。無効または失効したキーは HTTP 401（API_KEY_INVALID）を返します — ヘッダーを修正して再接続してください。有効期間を過ぎたキーは 401 と API_KEY_EXPIRED を返します — 代わりのキーを作成してください。グラントが切れた OAuth 接続は OAUTH_GRANT_EXPIRED を返します — 同意画面から認可フローをやり直してください。

プロトコルに関する注意

• リクエストごとに JSON-RPC 2.0 メッセージを 1 つ（または最大 20 件のバッチ）を POST します。レスポンスは application/json で、通知は 202 で確認応答されます。
• サーバーはステートレスです — セッション ID は発行も要求もされません。GET /mcp は 405 を返します（サーバープッシュストリームはありません）。
• UUID のパス引数はディスパッチ前に検証されます — UUID でない ID はインバンドのツールエラーを返し、別の操作が実行されることは決してありません。
• 受け入れられるプロトコルリビジョン: 2025-06-18、2025-03-26、2024-11-05。

ドキュメント

• ガイド — 概念と予約フローはここから始めてください。
• API リファレンス — すべてのエンドポイント、引数、スキーマ。
• AI 向け — OpenAPI 仕様と、そのまま貼り付けられるアシスタントのブートストラップ。
• openapi.json — ツールの生成元となる機械可読な仕様。