Sanka

Sanka MCP サーバー

このリポジトリには、ホスト型 Sanka MCP サービスと、Sanka の外部から呼び出し可能な API を呼び出すために使用する TypeScript クライアントが含まれています。現在は Stainless 管理のリポジトリではなく、通常の TypeScript ワークスペースとしてメンテナンスされています。

本番サービスは、リモートの Streamable HTTP MCP エンドポイントです。

• 主なエンドポイントは POST /mcp です
• SSE 形式のパスを引き続き想定しているクライアント向けの互換エイリアスは POST /sse です
• 互換エイリアスは POST / です
• ヘルスチェックには GET /health を使用します

/mcp エンドポイントは、一般的な SDK ツールと読み取り専用の CRM ツールの両方を、単一の MCP サーフェスから公開します。

本番エンドポイント：

• https://mcp.sanka.com/mcp
• https://mcp.sanka.com/sse

ステージングエンドポイント：

• https://sanka-mcp-staging.fly.dev/mcp

リポジトリの構成

• src/：MCP サービスで使用する、Sanka の外部から呼び出し可能な API 用 TypeScript クライアント
• src/internal/：パッケージ内限定の SDK ランタイムヘルパー。Sanka の非公開バックエンドコードではありません
• packages/mcp-server/：MCP サーバーアプリケーションと Docker エントリーポイント
• .github/workflows/：CI と、ステージングおよび本番への Fly デプロイ用ワークフロー
• fly.toml：本番 Fly アプリの構成
• fly.staging.toml：ステージング Fly アプリの構成
• docs/openapi-maintenance.md：Stainless を使わずに API カバレッジを最新に保つためのガイダンス

認証

ホスト型 HTTP クライアントは Connect Sanka を通じて認証します。MCP サーバーはリソースにバインドされたセッション ID を発行し、connect_sanka または保護されたツールの結果から署名済みの https://app.sanka.com/oauth/mcp/connect URL を返します。また、承認されたセッションを内部的に短期間有効な Sanka アクセストークンと交換します。この交換には POST /oauth/internal/mcp-session-token を使用します。

Sanka V2 が完全な認可コードサーバーを実装するまで、ネイティブ MCP OAuth は意図的に無効にしています。MCP サービスは OAuth 認可サーバーまたは保護リソースのメタデータを公開せず、クライアントが送信する Authorization および X-Sanka-API-Key ヘッダーを拒否します。トークン交換シークレットは sanka-mcp と sanka-api の間でのみ使用します。MCP クライアントに送信してはいけません。

ワークスペースの読み取りと成功した switch_workspace 呼び出しでは、MCP セッションが保持する解決済みワークスペース ID が更新されます。そのため、レコード URL の エンリッチメントでは、初期接続時に取得したコードを保持するのではなく、切り替え後すぐに選択されたワークスペースコードを使用します。ワークフローのプレビュー／開始呼び出しでも、送信直前に現在の MCP セッションを再読み込みし、リクエストをそのワークスペースにバインドします。API が別のワークスペースを解決した場合は、安全側に倒して処理を中止します。これにより、会計のドライランとワークフローへの書き込みは、current_workspace に表示されるテナントと同じテナントで実行されます。

Codex や Claude を含むすべてのホスト型クライアントは、同じ Connect Sanka URL フローを使用します。未認証の初期化リクエストとツール一覧リクエストは引き続き利用可能なため、クライアントは connect_sanka と保護されたツールのフォールバックを読み込めます。

開発者 API トークンによる MCP アクセスは、意図的にサポートしていません。MCP の外部での Sanka API および SDK の直接利用には、引き続き使用できます。

ローカル開発

pnpm install
pnpm build
export MCP_SERVER_AUTHORIZATION_SERVER_URL="http://app.localhost:8000"
export MCP_SERVER_INTERNAL_AUTHORIZATION_SERVER_URL="http://api.localhost:8000"
export MCP_SERVER_TOKEN_EXCHANGE_SHARED_SECRET="local-shared-secret"
export SANKA_BASE_URL="http://api.localhost:8000"
node packages/mcp-server/dist/index.js --transport=http --port=8080

ローカルの Sanka の前提条件：

• app.localhost:8000 が /oauth/mcp/connect を提供する
• api.localhost:8000 が /api/v2/public/* を提供する
• api.localhost:8000 が /oauth/internal/mcp-session-token を提供する
• MCP サーバーと API で、同じローカルのトークン交換シークレットを使用する

Stdio はローカル開発用のトランスポートとして引き続き使用できます。ここでの SANKA_API_KEY はプロセス構成であり、クライアントが送信するベアラーモードではありません。ホスト型クライアントは Connect Sanka を使用する必要があります。

続いて、次のように検証します。

curl http://127.0.0.1:8080/health
curl -sS -D - http://127.0.0.1:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'

静的な認証ヘッダーを設定せず、HTTP MCP クライアントの接続先を http://127.0.0.1:8080/mcp にします。connect_sanka または保護されたツールを呼び出し、返された Connect Sanka URL を開いてから、サーバーが発行した MCP セッション ID を使って再試行します。

Browser Use ワーカー

browser_use MCP ツールは、許可リストに登録されたブラウザーワークフローを別のワーカーにディスパッチします。MCP サーバーはセッション認証、監査メタデータ、ワークフローのルーティング、確認ゲートを管理し、ワーカーはブラウザーの状態とサードパーティの UI 操作を担当します。最初に登録されたワークフローは次のとおりです。

• demo.hubspot.company_avatar：CRM API では表示されるアバターを設定できない場合に、HubSpot UI を使って HubSpot のデモ企業のアバターを更新します。

agent-browser を使ってローカルワーカーを実行します。

npm install -g agent-browser
agent-browser install

export SANKA_BROWSER_USE_WORKER_TOKEN="local-worker-token"
export SANKA_BROWSER_USE_PROFILE_ROOT=".browser-use-profiles"
export SANKA_BROWSER_USE_ARTIFACT_DIR=".browser-use-artifacts"
pnpm --dir packages/mcp-server browser-use-worker

MCP サーバーからワーカーを指定します。

export SANKA_BROWSER_USE_WORKER_URL="http://127.0.0.1:8787/run"
export SANKA_BROWSER_USE_WORKER_TOKEN="local-worker-token"

本番環境では、たとえば Fly 上にワーカーを別サービスとしてデプロイし、SANKA_BROWSER_USE_PROFILE_ROOT に永続ボリュームをマウントして、HubSpot のログイン Cookie が再起動後も保持されるようにします。ワーカーは非公開にするかトークンで保護し、MCP サービスに公開するエンドポイントは /run のみにしてください。

Fly ワーカーアプリ、永続ボリューム、シークレットの設定、プロファイルのシード手順については、docs/browser-use-worker-fly.md を参照してください。

デプロイ

このリポジトリは packages/mcp-server/Dockerfile から Fly にデプロイされます。

• 本番環境への手動デプロイ：fly deploy -c fly.toml
• ステージング環境への手動デプロイ：fly deploy -c fly.staging.toml
• ステージング環境への自動デプロイ：staging へのプッシュ
• 本番環境への自動デプロイ：main を対象とする GitHub リリースの公開

リリースフロー

メインの Sanka アプリと同じ昇格フローを使用します。

1. 機能の PR を staging に作成します。
2. CI の成功後に staging をマージし、sanka-mcp-staging をデプロイします。
3. ステージングの MCP エンドポイントを検証します。
4. staging -> main の PR を作成します。
5. main の準備ができたら、Create new Sanka MCP Tag and Release を実行します。
6. リリースを公開すると本番環境にデプロイされます。

必須の Fly アプリとシークレット：

• 本番アプリ：sanka-mcp
• ステージングアプリ：sanka-mcp-staging
• ステージングで意図的に異なる認証スタックを使わない限り、両方のアプリに同じ MCP_SERVER_* シークレットを設定します。

リトライポリシー

TypeScript クライアントはデフォルトで、408、409、429、5xx、および接続エラーを 2 回リトライします。自動リトライが維持されるのは、metadata.operation: 'read' を持つツールのみです。すべての書き込みツールは API を 1 回呼び出し、エラーがあればエージェントに返します。書き込みは副作用が発生した後に失敗することがあります。たとえば、Gmail がメールを受け付けた後に Sanka が記録できなかった場合、リトライすると同じ処理が繰り返されます。また、API は配信ルートからのエラーに x-should-retry: false を設定します。返信ツールは DELIVERY_UNKNOWN を再送不可のエラーとして報告します。

メンテナンスの方針

このリポジトリは、実行時にも継続的な開発においても、Stainless プロジェクトへのアクセスに依存しなくなりました。API カバレッジはこのリポジトリで直接維持してください。

次のステップとして、TypeScript クライアントの更新には、ホスト型ジェネレーターへの依存を再導入するのではなく、オープンソースの OpenAPI ツールを採用することを推奨します。openapi-maintenance.md を参照してください。

このリポジトリには、スターターの型生成コマンドが含まれています。

pnpm generate:openapi-types

デフォルトでは、隣接する Sanka の仕様ファイル ../sanka-sdks/openapi.json を読み込みます。

Developer Cloud（リリース候補）

ホスト型ツールでは、CLI および SDK と同じ V2 のソース、実行、レシート、証明書、Fleet の契約が公開されています。このソースの変更によって、本番環境での実行が有効になることはありません。まず get_developer_cloud_availability を読み、各機能の利用可否フラグに従ってください。無料のローカル移行とクライアント証拠の登録に変更はありません。

すべての呼び出しで、固定された workspace_id が必要です。有料の作成と選択的な再試行には、明示的なリクエスト、承認済みの上限、confirm: true、および安定した idempotency_key が必要です。既存のユーザー認可で十分です。応答が失われても、新しいインテントを作成してはいけません。同一のキーとリクエストを読み戻すか、再送してください。どのツールもクレジットの購入、リポジトリへの PR 作成、マージ、デプロイは行いません。

• ソース／実行：upload_developer_cloud_source、create_developer_cloud_run、list_developer_cloud_runs、get_developer_cloud_run、cancel_developer_cloud_run。
• 証拠：list_developer_cloud_events、get_developer_cloud_receipt、list_developer_cloud_artifacts、download_developer_cloud_artifact。
• 証明書：list_developer_cloud_certificate_keys、get_developer_cloud_certificate、revoke_developer_cloud_certificate。
• Fleet：create_developer_cloud_fleet、list_developer_cloud_fleets、get_developer_cloud_fleet、cancel_developer_cloud_fleet、retry_developer_cloud_fleet。

修復と証明書の発行には、それぞれ create_developer_cloud_run.request.repair と .certification を使用します。コンピュート料金はワーカー分あたり 100 クレジットで、実行ごとに一度だけ端数処理されます。修復に成功すると 1,000 クレジットが加算されます。個別の証明書発行には 2,000 クレジットが加算されます。コンピュート料金と追加料金はすべて、承認済みの上限内に収まります。ゲートに失敗した場合、追加料金は発生しません。Fleet に追加料金はありません。上限額は明示された子実行の上限額の合計で、アトミックに確保されます。ワークスペースあたり、同時に稼働できるワーカーは最大 5 つです。再試行では、元の Fleet が完了した後に失敗した子実行のみを選択します。新しい Fleet を作成し、完了済みの子実行のレシートを保持します。

正確な ZIP のダイジェストと、宣言された完全なリビジョンをアップロードしてください。サービスはアップロードされたバイト列を固定しますが、Git の来歴を独自に証明することはありません。証明書のスコープ、シナリオ、制限事項、失効状態を確認してください。証明書をダウンロードしても署名は検証されません。公開鍵を使用して、CLI でオフライン検証を行ってください。アーティファクトのダウンロードでは、記録された SHA-256 メタデータと照合してバイト列を検証します。MCP で対応するサイズは最大 64 MiB です。それより大きなアーティファクトには CLI／API を使用してください。大容量のダウンロードでは、既存のセッションに紐づく URL または read_binary_download_chunk のフローを使用します。

リクエストスキーマの再生成では、共有 V2 SDK 入力を使用します。

python3 scripts/sync-developer-cloud-contract.py ../sanka-sdks/openapi.json
pnpm exec prettier --write packages/mcp-server/src/generated/developer-cloud-schemas.ts

埋め込みワークスペース

Sanka アプリでは、接続された完全な Flow ワークスペースが開きます。サイドバー、ダッシュボード、レコードテーブル、ワークフロー、レポートを利用できます。ワークスペース全体へのアクセスには、明示的な Sanka 認可が必要です。アクセス範囲がより限定された接続では認可コントロールが表示されます。以前の Invoice アシスタントのパイロット画面は、現在提供されていません。

ホスト型の Invoice MCP ツールは、従来のスコープと確認要件のまま引き続き利用できます。パイロット画面の削除によって、Invoice レコードや API の契約が変更されることはありません。