MCP サーバー

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

https://api.crisphive.com/mcp

要件

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_requests_view）をリクエストしてください。省略するとビジネスへのフルアクセスになります。アクセストークンの有効期間は約 1 時間です — 接続を維持するにはリフレッシュトークンを使用してください。

ツール

公開 /v1 API の操作ごとに 1 つ、合計 22 個のツールがあります — 名前は 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）を返します — ヘッダーを修正して再接続してください。

プロトコルに関する注意

• リクエストごとに 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 — ツールの生成元となる機械可読な仕様。