Thalovant MCP

最終編集：Codex（正確な実行時モデル識別子は不明） - 2026-10-25 - 理由：セキュリティ依存関係の互換性と次のパッチバージョンを記録します。

Thalovant MCP Server

Thalovant のコントロールプレーンおよびハブのランタイム API 向けの、公開運用に対応した MCP サーバーです。

公式の Thalovant Node.js SDK と本番環境用の MCP TypeScript SDK を、stdio および Streamable HTTP 経由で使用するため、Claude Desktop、Codex、Cursor などのローカル MCP ホストや、リモート MCP クライアントで動作します。

含まれる機能

• ローカルエージェント向けの stdio トランスポート。
• リモートエージェント向けの /mcp での Streamable HTTP トランスポート。
• /.well-known/oauth-protected-resource での OAuth スタイルの保護されたリソースメタデータ。
• シンプルな非公開デプロイ向けの静的ベアラートークン。
• 本番環境のリモートデプロイ向けの JWT/JWKS および OAuth トークンイントロスペクション。
• プリンシパルごとの Thalovant 認証情報とツールポリシー。
• ホスト／オリジンの検証、CORS、レート制限、リクエスト本文のサイズ制限、セキュアヘッダー、セッションバインディング。
• オプションの再開可能イベントストレージと JSONL 監査ログ。
• Docker、Compose、Kubernetes、CI、npm パッケージメタデータ、MCP レジストリの server.json。

TypeScript を選ぶ理由

Thalovant は Python、Node.js、Go、Rust 向けの SDK を公開しています。このサーバーでは Node.js を使用します。@thalovant/sdk が Thalovant のコントロールプレーン、ID の読み込み、WSS/HTTPS/MQTT ランタイムクライアント、メモリ、分析、コンテキストヘルパーを直接提供し、@modelcontextprotocol/sdk が、複数のエージェントに対応する stdio および Streamable HTTP サーバーを構築するうえで最もよくサポートされている方法だからです。

インストール

公開済みパッケージを npx -y @thalovant/mcp-server で実行するか、チェックアウトからビルドします。

npm install
npm run build

Node.js 20 以降が必要です。

コントロールプレーンの認証

公開ハブの検出に Thalovant の認証情報は不要です。非公開のコントロールプレーンツールとランタイムハブツールは、MCP サーバーの環境変数またはサーバー側のプリンシパル認証情報ファイルからのみ認証情報を読み込みます。API トークンやパスワードをチャットやツールの引数で渡さないでください。

サーバーは次の順序でコントロールプレーンの認証方法を選択します。

1. THALOVANT_API_TOKEN — スコープが設定された Thalovant API トークン。推奨。
2. THALOVANT_ACCESS_TOKEN — 発行済みのセッションアクセストークン。
3. THALOVANT_EMAIL + THALOVANT_PASSWORD — 対話型アカウントのログインへのフォールバック。

トークンが設定されている場合、サーバーはログインエンドポイントを呼び出しません。thalovant_config_status は、トークンの値を明かすことなく、アクティブなモードを controlPlaneAuthMode として報告します。

これらがいずれも設定されていない場合は、ブラウザーを使ってサーバーにサインインできます。デバイスサインインを参照してください。サインイン時に発行されるトークンは、上記のいずれも設定されていない場合にのみ使用されます。

デバイスサインイン

ツール呼び出しは人を待つことができないため、デバイスフロー（RFC 8628）は2つのツールで構成されています。

1. 任意の scopes（空のリストは指定なしと同じで、API のデフォルトを要求します）、clientName、clientId を指定して thalovant_begin_device_login を呼び出すと、loginId、userCode、verificationUri、verificationUriComplete、interval、expiresIn が返されます。URL とコードを人に表示してください。clientId を指定すると、登録済みアプリとしてサインインします。Home Assistant の場合は thalovant-home-assistant を指定します。承認ページでは、そのアプリのプラットフォーム名が認証済みとして表示され、再度承認すると、すでに保持しているトークンが置き換えられます。API が認識しない ID は拒否されます（400 unknown_client）。
2. その loginId を指定して thalovant_poll_device_login を呼び出すと、状態を一度確認します。outcome は pending（interval 秒後に再度確認します。API から待機時間を延ばすよう求められた場合に備え、あらかじめ5秒長く設定されています）、approved（tokenId、scopes、expiresAt を含みます）、expired、denied のいずれかです。

デバイスコードとトークンがモデルに渡ることはありません。サーバーはサインインを開始したプリンシパルに両方を紐付け、プロセスが存続する間保持します。承認されると、認証情報が設定されていない場合、そのプリンシパルのすべてのコントロールプレーンツールでトークンが使用されます。thalovant_revoke_device_login はサインアウトを行います。トークンを失効させ（トークンは常に自身を失効させることができ、すでに失効済みの場合も失効済みとして扱われます）、そのトークンを破棄します。再度サインアウトすると、リクエストを送信せずに alreadyRevoked が返されます。設定済みのトークンには一切触れません。サインインでアクセスするのは、設定された API オリジン（THALOVANT_API_URL、またはデフォルト）のみです。これは、応答として返される確認 URL を人に表示するためです。Home Assistant との連携では hubs:read、clients:read、clients:write が要求されます。これらは Free プランで承認可能な権限のすべてでもあります。

API トークン（AI エージェントと CI に推奨）

スコープ付き API トークンは、AI や自動化での使用に適した認証情報です。Thalovant ダッシュボード（またはデバイスフロー）から発行され、付与したスコープのみを持ち、個別に失効でき、アカウントのパスワードや MFA を使用する必要もありません。トークンのプレフィックスは tvpat_ です。

export THALOVANT_API_TOKEN="tvpat_..."
export THALOVANT_API_URL="https://api.thalovant.com"

npm start

すべてのコントロールプレーンツールを使用するために必要な最小スコープ：

スコープ	使用箇所
hubs:read	thalovant_list_hubs、thalovant_get_hub、thalovant_get_analytics_overview、thalovant_list_marketplace_skills、thalovant_list_runtime_groups、thalovant_get_runtime_group、thalovant_get_runtime_group_config、thalovant_update_runtime_group_config 内の保護されたマージ読み取り、および thalovant_create_client_identity 内のハブ検索
hubs:inspect	thalovant_get_hub_runtime_capabilities、thalovant_list_runtime_group_marketplace、thalovant_list_runtime_group_inventory、thalovant_list_hub_skills、thalovant_list_hub_skill_history
hubs:write	すべてのハブおよびランタイムグループのプロビジョニング：thalovant_create_hub、thalovant_update_hub、thalovant_release_hub、thalovant_create_runtime_group、thalovant_update_runtime_group、thalovant_update_runtime_group_config、thalovant_release_runtime_group、thalovant_install_runtime_group_skill、thalovant_uninstall_runtime_group_skill、ハブごとの thalovant_install_hub_skill、thalovant_update_hub_skill、thalovant_remove_hub_skill、ハブ評価ツール、およびオプトイン方式の削除ツール
clients:write	thalovant_create_client_identity（POST /v1/clients）およびオプトイン方式の thalovant_delete_client
memory:read	thalovant_list_memory_items、thalovant_get_memory_summary、thalovant_get_memory_item
memory:write	thalovant_create_memory_item、thalovant_update_memory_item、thalovant_delete_memory_item

ハブのスコープは相互に包含します。hubs:write は hubs:read を付与し、hubs:read は hubs:inspect と hubs:preview を付与します。そのため、hubs:read を指定してトークンを発行すれば、上の表にあるすべての検出ツールを使用できます。

プロビジョニングでは、スコープだけが条件ではありません。ハブおよびランタイムグループへの書き込みにはすべて有料プランも必要です。また、API はプランより先にスコープを確認するため、失敗の順序は次のとおりです。

• 必要なスコープがないトークンは 403 Insufficient scopes で失敗します。無料プランの API トークンで指定できるのは hubs:read、clients:read、clients:write に限られるため、無料プランではこの 403 が発生し、402 には到達しません。
• 適切なスコープを持つトークンでも、無料プランでは 402 API access requires a paid plan. で失敗します。
• プランが有料でも、access_tier: paid のカタログ項目が含まれていない場合、thalovant_install_runtime_group_skill は2つ目の別個の 402、This skill requires paid marketplace access for the tenant plan. で失敗することがあります。

検出機能には意図的に有料プランの制限を設けていません。無料プランのトークンでもマーケットプレイスのカタログを閲覧し、ハブを評価できますが、スキルのインストールやハブのプロビジョニングはできません。 インストール前に thalovant_list_runtime_group_marketplace を使用してください。スキルごとに installable、purchase_required、access_message が返されるため、内容の分かりにくい 402 エラーを事前に判断できます。

用途を限定したデプロイでは、必要最小限のスコープを付与してください。読み取り専用アシスタントに必要なのは hubs:read と memory:read のみです。また、スキルを閲覧するだけでプロビジョニングを行わない検出専用エージェントには、hubs:read のみで十分です。admin: true を指定した thalovant_get_analytics_overview には、admin:analytics を持つ管理者アカウントも必要です。通常の用途で使う API トークンには、このスコープを付与しないでください。ランタイムハブツール（thalovant_ask、thalovant_send_action など）では、コントロールプレーントークンではなく Thalovant クライアント ID を使用します。

ハブの ETag

thalovant_update_hub と thalovant_delete_hub は楽観的ロックを使用し、If-Match として送信するハブの現在の etag が必要です。etag はハブリソースの本文でのみ取得できます。API は ETag レスポンスヘッダーを送信しないため、エージェントはまず thalovant_get_hub を呼び出し、そのレスポンスの etag フィールドを渡す必要があります。値がない場合や古い場合は 412 ETag mismatch となり、変更は行われません。再取得して再試行してください。name、namespace、domain は作成後に変更できないため、thalovant_update_hub はこれらを一切受け付けません。ハブリソース全体をそのまま送り返すのではなく、変更するフィールドだけを送信してください。ランタイムグループへの書き込みでは etag は使用しません。

ハブスキル

thalovant_list_hub_skills、thalovant_install_hub_skill、thalovant_update_hub_skill、thalovant_remove_hub_skill は、ハブに関連付けられたランタイムグループを対象にします。そのランタイムグループを共有するすべてのハブに影響します。ハブにはスキルがまったくない状態で開始し、1 つずつ追加できます。変更は再起動なしで約 15 秒後にハブへ反映されます。hubId にはハブの UUID を指定する必要があります。認証済みのハブルートではスラッグは拒否されます。

thalovant_list_hub_skills は、GET /v1/hubs/{hub_id}/skills のエンベロープ全体を返します。内容は、hub_id、runtime_group_id、observed_at、source、ランタイムのフェーズとメッセージ、およびスキルごとに 1 行（空の場合もあります）の data です。各行には、skill、title、marketplace_skill_id、package_name、source_type、install_source、version、version_pin、installed_version、observed_version、previous_version、latest_version、available_version、update_available、changelog、active、state、ランタイムのフェーズ、メッセージ、最終エラー、および last_transition_at が含まれます。state は pending、installed、failed、removing、drifted、quarantined、unmanaged のいずれかです。変更の進行中は pending と表示されます。

各書き込みは、operation_id、hub_id、runtime_group_id、skill、version（削除の場合は null）、previous_version、state（installing、updating、removing のいずれか）を含む 202 を返します。wait: true を渡すと、操作が収束するまで（installed、削除の場合は removed）2 秒ごとにポーリングします。操作が failed または timed_out になると、error_message を含むエラーが発生します。デフォルトの timeoutMs は 120 秒です。または、thalovant_get_operation を使って手動で追跡できます。すでに別のバージョンでインストール済みのスキルをインストールすると更新が実行されます。同じバージョンの場合は、コード skill_version_already_installed を伴う 409 エラーになります。ランタイムグループのないハブでは、コード hub_without_runtime_group を伴う 404 エラーになります（通常の 404 は、存在しないハブまたはインストールされていないスキルを示します）。解決できない latest や無効なバージョンの場合は 422 エラーになります。エラーは RFC 7807 の problem 本文で返されます。ツールのエラーには短い message が保持され、その末尾に括弧付きでルートの code が追加されます。たとえば、Thalovant API request failed with HTTP 409: Skill version already installed. (skill_version_already_installed) のようになります。その後にコードと本文のその他のフィールドが続きます（ツールエラーを参照）。

一覧表示には hubs:inspect（hubs:read に含まれます）が必要です。書き込みには hubs:write と有料プランが必要です。スコープの確認がプランの確認より先に行われるため、無料プランのトークンでは 402 ではなく必ず 403 が返されます。ハブ制限付きトークン（hub_ids の許可リスト）は、4 つすべてのルートで尊重されます。サーバーは公開されている Node SDK のハブスキルメソッドを使用し、ポーリング中も MCP のキャンセル確認を維持します。ステータスの読み取りに失敗しても、受理済みの操作 ID は保持されます。書き込みを再送信するのではなく、その ID を使って thalovant_get_operation を呼び出してください。ポーリング期限以降に新たなポーリングは開始されません。この期限によって、すでに実行中の HTTP リクエストがキャンセルされることはありません。

ログインへのフォールバック

export THALOVANT_EMAIL="[email protected]"
export THALOVANT_PASSWORD="..."

export THALOVANT_PROFILE="prod"
export THALOVANT_API_URL="https://api.thalovant.com"

npm start

トークンもメールアドレス／パスワードも設定されていない場合、認証が必要なコントロールプレーンツールは、利用可能なオプションを明示したエラーを返します。

設定された API トークンとログイン認証情報は、設定された apiUrl または THALOVANT_API_URL（デフォルトは https://api.thalovant.com）のオリジンに紐付けられます。ツールの引数で、これらの認証情報を別のオリジンに転送することはできません。同じオリジン上での同等の URL 表記やパスは許可されます。カスタムオリジンを使用する場合は、その認証情報と併せて設定する必要があります。匿名での公開情報の検索では、引き続きカスタム API URL を選択できます。

Home Assistant のリンク

Home Assistant などのホームコントローラーは、同じ種類の接続を持つハブにリンクします。

1. トークンが設定されていない場合は、サインインします：デバイスのサインイン。
2. thalovant_create_client_identity を connectionType: "home_assistant" とともに実行します。API は同じ種類を返す必要があります。通常の接続を作成した場合は、その接続が削除され、呼び出しは失敗します。結果には clientId、connectionType、operationId が含まれます。
3. その operationId を指定して thalovant_wait_for_admission を実行します。ハブが新しい接続を許可するまで約90秒かかり、それまでは拒否されます。outcome は admitted、failed、timeout のいずれかです。プラットフォームで失敗した場合は、操作の errorCode が返されます（status は null）。API 自体が待機を拒否した場合は、その status、code、detail が返されます。timeout になっても接続が許可される可能性はあります。別の接続を作成するのではなく、ツールを再度呼び出してください。429 の場合は、API が指定する時間だけ待機します（本文、次に Retry-After、それがなければ RateLimit-Reset の値）。指定された待機時間が残り時間を超えている場合は、直ちに timeout になります。API が拒否したトークン（401、403）と、到達できない API は、それぞれ独自のヒントを含むツールエラーとなり、接続許可の失敗として扱われることはありません。このツールは読み取り専用で、キャンセルに対応し、API と異なるオリジンへの links.self をたどることはありません。

ステップ2が拒否された場合は、API 自身のテキストに続けて、次に行うべきことが示されます（ツールエラーを参照）。例としては、API がまだ認識していない種類、接続を許可しないプラン、Home Assistant のリンクをすでに1つ保持しているハブ（それを保持している client_id が示されます）、または API が拒否したトークン（再度サインインしてください）があります。thalovant_delete_client は接続を削除します（If-Match を使用し、指定されていない場合は先に etag を読み取り、412 の場合は1回再試行し、すでに削除されている接続も削除済みとして扱います）。これは、オペレーターが有効化する破壊的なツールです。

その後にハブからのリクエストに応答することは、データプレーン上で動作する、連携機能独自の長時間実行ジョブです。MCP ツール呼び出しがハブとの接続を維持するのは、その呼び出しの実行中だけです。そのため、リンクのこの部分はツールではありません。

ローカルの Stdio

サーバーは stdio 経由で MCP を使用し、stdout にログを書き込みません。

実行時のハブツールは、次の順序でローカルの ID を読み込みます。

1. ツール引数の identityFile。
2. ツール引数の configPath または profile。
3. Thalovant SDK の環境 ID 変数。
4. デフォルトの Thalovant SDK 設定プロファイル。

Thalovant の ID ファイルは秘密にしてください。SDK は、~/.config/thalovant/config.yaml などの保護された設定ファイルに 0600 のモードが設定されていることを想定しています。

Streamable HTTP

リモートモードでは /mcp で MCP Streamable HTTP を使用し、デフォルトでベアラー認証が必要です。

export MCP_TRANSPORT="http"
export MCP_HTTP_HOST="127.0.0.1"
export MCP_HTTP_PORT="3000"
export MCP_HTTP_AUTH_TOKEN="$(openssl rand -hex 32)"
export MCP_HTTP_ALLOWED_HOSTS="127.0.0.1:3000,localhost:3000"

npm run start:http

クライアントは次の URL に接続します。

http://127.0.0.1:3000/mcp
Authorization: Bearer <token>

ヘルスチェックには /healthz と /readyz を使用できます。

公開環境にデプロイする場合は、公開 URL と、正確なホスト／オリジンの許可リストを設定します。

export MCP_HTTP_HOST="0.0.0.0"
export MCP_HTTP_PORT="3000"
export MCP_PUBLIC_URL="https://mcp.example.com"
export MCP_HTTP_ALLOWED_HOSTS="mcp.example.com"
export MCP_HTTP_ALLOWED_ORIGINS="https://agent.example.com"

リモート認証

静的ベアラートークンは、ローカル環境、プライベート環境、またはシングルテナント環境のデプロイでのみ使用してください。

export MCP_HTTP_AUTH_TOKEN="$(openssl rand -hex 32)"
# or
export MCP_HTTP_AUTH_TOKENS="token-a,token-b"

本番環境でリソースサーバーの検証を行う場合は、JWT/JWKS を使用してください。

export MCP_HTTP_AUTH_MODE="jwt"
export MCP_OAUTH_ISSUER="https://auth.example.com/"
export MCP_OAUTH_JWKS_URL="https://auth.example.com/.well-known/jwks.json"
export MCP_OAUTH_AUDIENCE="https://mcp.example.com/mcp"
export MCP_OAUTH_AUTHORIZATION_SERVERS="https://auth.example.com/"
export MCP_OAUTH_REQUIRED_SCOPES="mcp:thalovant"

認可サーバーが不透明なトークンを発行する場合は、イントロスペクションを使用してください。

export MCP_HTTP_AUTH_MODE="introspection"
export MCP_OAUTH_INTROSPECTION_URL="https://auth.example.com/oauth2/introspect"
export MCP_OAUTH_CLIENT_ID="mcp-server-client"
export MCP_OAUTH_CLIENT_SECRET="..."
export MCP_OAUTH_AUDIENCE="https://mcp.example.com/mcp"
export MCP_OAUTH_AUTHORIZATION_SERVERS="https://auth.example.com/"
export MCP_OAUTH_REQUIRED_SCOPES="mcp:thalovant"

サーバーは、保護されたリソースのメタデータを次の場所で公開します。

https://mcp.example.com/.well-known/oauth-protected-resource

401 のレスポンスには WWW-Authenticate が含まれ、OAuth ディスカバリーに対応する MCP クライアント向けに resource_metadata の参照先が示されます。

Principal Credentials

複数ユーザー向けのリモートデプロイでは、すべての MCP ユーザーで1つの Thalovant アクセストークンを共有しないでください。認証済みの各 MCP プリンシパルに、それぞれ専用の Thalovant コントロールプレーントークン、ランタイム ID、ツールポリシーを割り当てます。

単一ファイル：

export THALOVANT_PRINCIPAL_CREDENTIALS_FILE="/run/secrets/thalovant-principals.json"

ディレクトリモード：

export THALOVANT_PRINCIPAL_CREDENTIALS_DIR="/run/secrets/thalovant-principals"

ディレクトリ内のファイル名は <sha256(principal-id)>.json です。サーバーは OAuth のサブジェクト、プリンシパル ID、クライアント ID を確認します。examples/principal-credentials.sample.json を参照してください。

すべてのリモートプリンシパルにサーバー環境の Thalovant 認証情報を使用させる場合を除き、複数ユーザー向けのデプロイではこれを無効のままにしてください。

export THALOVANT_ALLOW_SHARED_CREDENTIALS="false"

リモートプリンシパルでは、ランタイムの identityFile、configPath、profile、fromEnv ツール引数はデフォルトで無効になっています。信頼できるプライベート環境でのみ MCP_HTTP_ALLOW_CLIENT_CREDENTIAL_PATHS=true を設定してください。

ポリシー、監査、再開可能性

グローバルツールポリシー：

export MCP_TOOL_ALLOWLIST="thalovant_*"
export MCP_TOOL_DENYLIST="thalovant_delete_memory_item"

プリンシパルごとの認証情報ファイルには、allowedTools と deniedTools も含めることができます。

どちらも呼び出し時のフィルターです。許可リストが空の場合は「すべて許可」を意味します。ツールをデフォルトで無効にしたり、tools/list から非表示にしたりすることはできません。そのため、破壊的操作を行う2つのコントロールプレーンツールは、THALOVANT_ENABLE_DESTRUCTIVE_TOOLS で個別に制御します。破壊的ツールを参照してください。

監査ログ：

export MCP_AUDIT_LOG="stderr" # off, stderr, file, or both
export MCP_AUDIT_LOG_FILE="/var/log/thalovant-mcp/audit.jsonl"
export MCP_AUDIT_INCLUDE_ARGS="false"

監査エントリは JSONL 形式で、認証情報に該当するフィールドは秘匿されます。

Streamable HTTP の再開可能性では、デフォルトでメモリ内イベントストアを使用します。単一インスタンスの再起動に備えるには、ファイルベースのストアを使用してください。

export MCP_EVENT_STORE_FILE="/var/lib/thalovant-mcp/events.jsonl"

HTTP のセキュリティ強化

• MCP_HTTP_ALLOW_UNAUTHENTICATED=true を明示的に設定しない限り、ベアラー認証が必要です。
• DNS リバインディングのリスクを軽減するため、Host ヘッダーは許可リストで制限されます。
• ブラウザーの Origin ヘッダーは、MCP_HTTP_ALLOWED_ORIGINS と完全に一致しない限り拒否されます。
• CORS で公開されるのは MCP のセッション／プロトコルヘッダーのみです。
• セッション ID には暗号学的に安全な乱数が使われ、認証済みプリンシパルにひも付けられます。
• リクエストボディの上限は MCP_HTTP_MAX_BODY_BYTES で設定され、デフォルトは 1 MiB です。
• 固定ウィンドウ方式のレート制限では、クライアントアドレスごとに1分あたり120件の MCP リクエストがデフォルトで許可されます。
• セキュリティヘッダーには、nosniff、DENY によるフレーミング制限、リファラーの無効化、制限的な CSP が含まれます。

HTTP 関連の主な環境変数：

MCP_HTTP_PATH=/mcp
MCP_HTTP_RATE_LIMIT_MAX=120
MCP_HTTP_RATE_LIMIT_WINDOW_MS=60000
MCP_HTTP_SESSION_TTL_MS=3600000
MCP_HTTP_MAX_BODY_BYTES=1048576
MCP_HTTP_ENABLE_JSON_RESPONSE=false
MCP_HTTP_TRUST_PROXY=false

Claude Desktop

推奨：スコープを限定した API トークンで認証し、MCP 設定にアカウントのパスワードが含まれないようにします。

{
  "mcpServers": {
    "thalovant": {
      "command": "npx",
      "args": ["-y", "@thalovant/mcp-server"],
      "env": {
        "THALOVANT_API_TOKEN": "tvpat_...",
        "THALOVANT_PROFILE": "prod"
      }
    }
  }
}

Codex

MCP クライアントの設定で、同じ stdio コマンドを使用します。

{
  "mcpServers": {
    "thalovant": {
      "command": "npx",
      "args": ["-y", "@thalovant/mcp-server"],
      "env": {
        "THALOVANT_API_TOKEN": "tvpat_...",
        "THALOVANT_PROFILE": "prod"
      }
    }
  }
}

ツール

読み取り専用：

• thalovant_config_status
• thalovant_list_public_hubs
• thalovant_get_public_hub
• thalovant_list_hubs
• thalovant_get_hub
• thalovant_get_operation
• thalovant_wait_for_admission
• thalovant_identity_status
• thalovant_healthcheck
• thalovant_intent_inventory
• thalovant_wait_for_event
• thalovant_get_analytics_overview
• thalovant_list_memory_items
• thalovant_get_memory_summary
• thalovant_get_memory_item

スキルとランタイムグループの検出（読み取り専用）：

• thalovant_list_marketplace_skills
• thalovant_list_runtime_group_marketplace
• thalovant_list_runtime_group_inventory
• thalovant_list_runtime_groups
• thalovant_get_runtime_group
• thalovant_get_runtime_group_config
• thalovant_get_hub_runtime_capabilities

サインイン（デバイスサインインを参照）：

• thalovant_begin_device_login
• thalovant_poll_device_login
• thalovant_revoke_device_login

書き込みまたはハブイベント：

• thalovant_create_client_identity
• thalovant_ask
• thalovant_query
• thalovant_send_action
• thalovant_send_code
• thalovant_emit_event
• thalovant_create_memory_item
• thalovant_update_memory_item
• thalovant_delete_memory_item

ハブとランタイムグループのプロビジョニング：

• thalovant_create_hub
• thalovant_update_hub
• thalovant_release_hub
• thalovant_set_hub_rating
• thalovant_clear_hub_rating
• thalovant_create_runtime_group
• thalovant_update_runtime_group
• thalovant_update_runtime_group_config
• thalovant_release_runtime_group
• thalovant_install_runtime_group_skill
• thalovant_uninstall_runtime_group_skill

ハブの共有ランタイムに作用するハブスキル（Hub Skillsを参照。リストツールは読み取り専用です）：

• thalovant_list_hub_skills
• thalovant_list_hub_skill_history
• thalovant_install_hub_skill
• thalovant_update_hub_skill
• thalovant_remove_hub_skill

破壊的な操作を行うため、明示的に有効化しない限り登録されません（Destructive Toolsを参照）：

• thalovant_delete_hub
• thalovant_delete_runtime_group
• thalovant_delete_client

ツールの出力では、認証情報のような形式のフィールドがマスキングされます。thalovant_create_client_identityは秘密のID情報を返しません。ID情報全体をモード0600でローカルファイルに書き込む場合は、savePathを指定してください。savePathはサーバーのIDディレクトリ（THALOVANT_MCP_IDENTITY_DIR、デフォルトは<config-dir>/thalovant/identities）内に限定されます。絶対パスでこのディレクトリの外を指定したり、..で上位のディレクトリに移動したりする指定は拒否されるため、モデルが認証情報ファイルをGit作業ツリーや同期フォルダーに置くことはできません。thalovant_config_statusは有効なidentityDirを報告します。

thalovant_intent_inventoryはランタイムIDを使用し、languages、describe、fallback、speakable、sentence、slots、exampleLimit、およびクエリまたはバッチごとのtimeoutMsを受け付けます。要求された言語ごとに、登録済みのインテントと例、フォールバックスキル、fallbacks_known、listed_in、may_answerを返します。listed_inは、要求された各言語がハブ内でどの言語として登録されているかを示します。ハブは読み込んでいない言語には何も登録しないため、文がない言語は通常の形式（en-USにおけるen-CAなど）か、ハブが読み込んだ最も近い言語で登録され、examplesもその言語で表示されます。listed_inが要求された言語と異なる場合、文は別の言語であり、その旨はpresentation.notesに記載されます。フォールバックスキルはスキルID順でovos.skills.listから取得され、priority: nullとなります。ハブは試行順を示しません。フォールバックスキルのクエリが見つからない場合や拒否された場合は、既知の空リストとしてではなく、不明として扱われます。オプションのプローブによる追加時間は最大1500msです。サイレントな一覧取得ではエンジンマニフェストを使用できます。これを無効にするにはfallback: falseを指定してください。新しい2つのツールはどちらも読み取り専用モードで使用でき、プリンシパルごとのポリシーに従います。thalovant_get_operationは、プロビジョニングによって返された操作IDを読み取りますが、書き込みを再実行することはありません。

追加されるpresentationオブジェクトには、共有SDKインベントリの構造であるcache_version、hub_id、hub_name、source、generated_at、skills、notes、languages_presentが含まれます。スキルタイトルはIDから導出されます。ランタイムの検出ではカタログのロケールやハブの表示メタデータを証明できないため、説明を含むメモを添えて、これらのフィールドは不明（空のリストまたは文字列）のままとなります。インテントの言語順は明示され、JSONキーの並べ替え後も維持されます。各ツール呼び出しはそれぞれ独自のIDリースを保持します。サーバーはインベントリを永続化せず、呼び出し元間でセッションを共有しません。

ツールエラー

Thalovant API がコントロールプレーンの呼び出しを拒否すると、ツールの結果はエラーになり、そのテキストは SDK の1行メッセージ（HTTP ステータスを示し、短縮される場合があります）で始まり、その後に API の応答全文が続きます。

Thalovant API request failed with HTTP 403: Only an administrator can run an image the platform does not release: bus may be one of ghcr.io/thalovant/ovos-messagebus:2026.09.2, ... (platform_image_required)
code: platform_image_required
detail: Only an administrator can run an image the platform does not release: bus may be one of ghcr.io/thalovant/ovos-messagebus:2026.09.2, ghcr.io/thalovant/ovos-messagebus:2026.09.3-alpha.1, ghcr.io/thalovant/ovos-messagebus:2026.08.7; core may be any tag or digest of ghcr.io/thalovant/ovos-core.
fields: {"allowed_images":{"bus":[...],"core":[...]},"allowed_repositories":{"core":"ghcr.io/thalovant/ovos-core"},"component":"runtime_group","refused_images":{...}}

• code は、API が返した場合の、API の機械可読コードです。
• detail は文全体で、1行目を短縮する必要があった場合にのみ表示されます。
• fields は、エラー本文のその他すべてのメンバーをコンパクトな JSON 形式で示したものです（Problem+JSON の type、title、status、instance は除外されます）。ほかのすべてのツール出力と同じ方法で秘密情報がマスキングされます。検証エラーでリクエストからそのまま返される値（detail または errors リスト内の各エントリーの input。キーや形式は問いません）は、ここでは "[omitted]" に置き換えられ、1行目にも表示されません。プランによる拒否では、ここに resource、limit、used、plan が含まれます。

ヒントが必要なステータスでは、ヒントが続く場合があります。platform_image_required または plan_limit の403エラーには、一般的なスコープのヒントではなく、それぞれ固有のヒントが表示されます。

リクエストのヒント、埋め込み音声、設定のマージ

thalovant_ask は、sttLang、順序付きの pipeline、および必須の city と、任意の region、country、timezone、latitude、longitude を含む location を受け付けます。ヒントは現在のリクエストに適用されます。使用しないヒントは省略してください。空のパイプラインは無視され、空白のみの言語文字列や都市名文字列は拒否されます。

Ask と Query は、言語、順序付きのイベントメタデータ、hasAudio、droppedMedia を返します。埋め込みの16進データはテキスト出力に含まれません。includeAudio: true を指定すると、MCP の音声ブロックを別々に受け取れます。不明な形式は、埋め込みのバイナリーリソースブロックになります。クリップと返信の上限はそれぞれ4 MiBと16 MiBで、保持前に SDK によってチェックされます。再生はクライアントが行います。スキルから提供されたパスや URL は取得されません。インベントリの speakable: true は、元のパターンを変更せずに例を表示します。slots は例示用のスロット値を指定し、exampleLimit は言語ごとの例の数を1～20（デフォルトは2）に制限します。

設定の更新はデフォルトで merge: true です。リビジョンを GET し、呼び出し元の差分をディープマージして、expected_revision を指定して PUT します。再試行されるのは HTTP 412 の場合のみで、新たに読み込み直して、合計最大3回試行します。これには hubs:read、hubs:write、および有料プランが必要です。リビジョンに対応していない旧バージョンの API では、書き込み前に失敗します。無条件のフォールバックはありません。指定されたペルソナは置き換えられ、省略されたペルソナは変更されません。意図的に全体を置き換える場合は merge: false を指定してください。その場合、hubs:write、有料プラン、およびほかの書き込み元との調整が必要です。ガード付きマージでは、書き込み前に、差分または保存済みの設定内にある JavaScript の安全な整数範囲を超える整数を拒否します。大きな識別子は文字列として保存するか、大きな JSON 整数を保持できる SDK を使用してください。

破壊的なツール

thalovant_delete_hub、thalovant_delete_runtime_group、thalovant_delete_client は、デフォルトで無効になっています。呼び出し時にブロックされるだけではなく、登録自体されないため、tools/list に表示されず、モデルから見たり、呼び出しを試みたりすることもできません。

有効期間の長いコントロールプレーントークンと、常時利用可能な削除ツールを組み合わせた場合のリスクは、読み取りツールや更新ツールとは根本的に異なります。ハブを削除すると、依存するクライアントと ACL も削除され、どの操作も取り消せません。そのため、これらのツールはオプトイン方式です。

export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true"

受け付ける true 値は 1、true、yes、on です。未設定を含め、それ以外の値ではツールは無効のままです。このフラグはサーバーインスタンスの作成時に読み込まれます。変更後は、環境を更新してサーバープロセスを再起動してください。thalovant_config_status は現在の状態を destructiveToolsEnabled として報告し、このフラグが制御するツールを一覧表示します。

これは既存のツールポリシーとは意図的に分離された仕組みです。MCP_TOOL_ALLOWLIST／MCP_TOOL_DENYLIST と、プリンシパルごとの allowedTools／deniedTools は呼び出し時のフィルターであり、許可リストが空の場合は「すべて許可」を意味します。オペレーターが有効にするまでツールを無効にしておくことは表現できず、tools/list からツールを隠すこともできません。THALOVANT_ENABLE_DESTRUCTIVE_TOOLS を設定すると、削除ツールは通常のツールとして扱われ、引き続きそのポリシーの適用を受けます。そのため、2 つのレイヤーは併用されます。

# Register delete tools, then deny their use by every principal.
export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true"
export MCP_TOOL_DENYLIST="thalovant_delete_hub,thalovant_delete_runtime_group"

グローバル拒否設定はすべてのプリンシパルに適用され、プリンシパルの allowedTools で上書きすることはできません。選択したプリンシパルだけを制限するには、これらのツールをグローバル拒否リストから除外し、該当するプリンシパルの deniedTools を使用してください。

ハブを削除するには引き続き最新の etag が必要です（指定しない場合は 412）。ランタイムグループがワークスペースのデフォルトである場合、またはハブがまだ接続されている場合、その削除は 409 で失敗します。クライアントを削除すると、それを使用しているデバイスまたはリンクが切断されます。etag が指定されていない場合は、まず読み取られます。

カタログ以外のスキルソース

thalovant_install_runtime_group_skill は、デフォルトで審査済みのマーケットプレイスカタログからインストールします。それ以外のソース、特に任意の sourceRef リポジトリー URL を指定する sourceType: "git" は、マーケットプレイスで一度も審査されていないコードを本番ランタイムに直接取り込みます。また、コントロールプレーンのバリデーターは形式のみを検証し、ホストの許可リストはありません。ツールは有効期間の長いトークンを持つモデルによって操作されるため、オペレーターがオプトインしない限り、カタログ以外のソースは拒否されます。

export THALOVANT_ENABLE_GIT_SKILL_SOURCES="true"

フラグが未設定の場合、catalog 以外の sourceType を指定した呼び出しは、コントロールプレーンへのリクエストが行われる前に失敗します。受け付ける true 値は 1、true、yes、on です。thalovant_config_status は状態を gitSkillSourcesEnabled として報告します。このツールには destructiveHint: true の注釈が付いています。

読み取り専用モード

THALOVANT_MCP_READONLY=1 を設定すると、readOnlyHint: true の注釈が付いたツールだけが登録されます（サインインツールは該当しませんが、thalovant_wait_for_admission は該当します）。書き込みツールと破壊的なツールは登録されず、tools/list にも表示されないため、オペレーターは拒否リストを手書きせずに、監視専用のエージェントを実行できます。他の登録時ゲートと同様、この設定はサーバーインスタンスの作成時に読み込まれます。thalovant_config_status は状態を readOnly として報告します。

HiveMind ランタイムの互換性

同じハブクライアント ID を共有するランタイム呼び出しは、1 つの MCP プロセス内で順番に実行されます。ハブが各セッションを分離できるよう、 独立して実行される MCP サーバーごとに異なるクライアント ID を使用してください。

バージョン 0.6.6 には @thalovant/sdk ^0.9.9（0.9.9 から 0.10.0 未満まで）が必要です。0.5.1 以降、サーバーは 有効な MQTT URL が安全であることを強制し、MQTT のセットアップと HTTP の失敗時のクリーンアップに 単一の接続期限を適用します。ランタイムツールは、WSS、HTTPS、TLS 経由の MQTT で HiveMind v3 Noise をサポートします。thalovant_healthcheck は認証後にのみ準備完了を 報告します。ハブまたはブローカーに到達できるだけでは、ランタイムセッションが確立されたことにはなりません。

Zod 4 のセキュリティ移行では、デフォルトの 50 個のツールと、文字列キーのレコード値が維持されます。JSON Schema の出力では、重複するレコードをインライン化し、文字列のプロパティ名を明示し、ストリッピングを行うオブジェクトでは additionalProperties: false を省略します。ハンドラーに渡される前に、未知の入力キーは引き続きストリッピングされます。UUID の検証では標準のバージョン／バリアントビット（nil/max UUID も含む）が必須となり、メモリ一覧のオフセットには安全な整数が必須となりました。根拠とリリースゲートについては、セキュリティ監査を参照してください。

サーバーの再起動後も、SDK の設定ディレクトリを永続化し、プライベートに保ってください （~/.config/thalovant、または設定されている XDG／Windows の同等の場所）。このディレクトリには、 クライアントの Noise キーと信頼済みサーバーのピンが含まれます。認証に失敗しても、 これらのピンは保持されます。サーバーキーの置き換えには、明示的に検証された 信頼の変更が必要です。HTTPS の ID ではハブの HTTPS プラグインを通知する必要があり、 MQTT では ID のブローカー認証情報とトピックプレフィックスが必要です。

ランタイムツールは、実際のクリーンアップが完了するまで ID のリースを保持します。クローズの 呼び出し元がタイムアウトした場合、後続のツールはセッションを開く前に、そのクリーンアップを最大 6 秒間待ちます。 この期限に達したキュー内のツールは、後から実行されたり、前のセッションの ID を解放したりせずに失敗します。 実際のクリーンアップに失敗した場合、同時セッションのリスクを避けるため、その ID は後続の呼び出しで 利用不可として扱われます。これらのリースはプロセス内でのみ有効です。別々のサーバープロセスやレプリカでは、 異なるランタイム ID または外部の調整が必要です。

MCP リクエストのキャンセルは、stdio と Streamable HTTP の両モードで、キュー内のランタイムツールに適用されます。 キャンセルされたキュー内の呼び出しでは、ランタイムクライアントは作成されず、後から実行されることもありません。キャンセルは、 ランタイムの接続セットアップ、Ask、Query、イベント待機にも伝播します。アクション／コードの送信、未加工のイベント公開、 インベントリクエリは、接続セットアップ中にキャンセルを確認します。その後は、許可された SDK 操作が完了するまで所有権を保持します。 MCP リクエストをキャンセルしても、すでに許可された操作やその影響を取り消すことはできません。アプリケーションのリクエストが 自動的に再送信されることはありません。作業中および実際のクリーンアップ中も ID は予約されたままです。 このリリースでは、コントロールプレーンツールにランタイムのキャンセルセマンティクスは適用されません。

たとえば、MCP TypeScript クライアントでは、ID のリース待ち時間も含めて、10 秒後にランタイムクエリをキャンセルできます。

await mcpClient.callTool({
  name: "thalovant_query",
  arguments: { identityFile: "/secure/identity.json", text: "What is the weather?", timeoutMs: 30000 },
}, undefined, { signal: AbortSignal.timeout(10000) });

インテントインベントリでは、接続セットアップとクエリ／バッチごとの予算に加え、 独立したオプションのフォールバックプローブが維持されます。インベントリ全体に適用される単一の期限はありません。

開発

npm run typecheck
npm test
npm run build
npm run test:smoke
npm run test:http
npm run bench
npm run bench:http
npm pack --dry-run

ライセンス

MITです。公開統合サーバーには適切なデフォルトです。寛容なライセンスであり、MIT Thalovant Node SDKおよびMCP TypeScript SDKと互換性があり、下流のエージェントやエンタープライズユーザーに相互ライセンスモデルを強制しません。

認証情報を伴うコントロールプレーンの呼び出しにはHTTPSが必要です。明示的なループバックHTTP （localhost、127.0.0.1、[::1]）は、ローカル開発で引き続きサポートされます。 パスワードログインの本文が転送されないよう、APIリダイレクトは拒否されます。 ランタイムクライアントは、IDリースを取得した後にのみ構築されます。

thalovant_queryはルーティングされたHiveMindクエリを送信します。ハブはルーティングポリシーに従って、これをカスケード処理する場合があります。text、timeoutMs、lang、sessionId、 requestId、queryId、context、replySettleMsに加え、ランタイムID オプションを受け付け、thalovant_askと同じ正規化された応答形式を返します。クエリはアクションを実行する可能性があるため、読み取り専用モードでは非表示になります。会話のワークフローでは、ask/queryと既存のイベント待機ツールで sessionIdを使用します。MCPでは、SDKのすべての会話メソッドやイベントリスナーメソッドに対して個別のツールは用意されていません。

共有ランタイムのスキル管理

カタログには、デフォルトで50個、読み取り専用モードで24個、破壊的なツールを有効にした場合は53個のツールがあります。

ハブを指定するスキルメソッドは、ハブUUIDに関連付けられたランタイムグループを選択します。 同じグループを共有するすべてのハブに、同一のスキル変更と履歴が適用されます。APIでは、制限付きトークンが提供対象のすべてのハブを対象としている必要があります。読み取りには hubs:inspect（hubs:readにその権限も含まれます）が必要です。書き込みにはhubs:write、対象となる有料プラン、および所有権が必要です。

履歴の応答には、新しい順のeventおよびoperationエントリが含まれます。 アクター／バージョンのフィールドはnullの場合があります。上限は1～200です（省略時は50）。 変更が受け付けられたことは、スキルが利用可能になった証明ではありません。任意の待機では操作の状態をポーリングします。デフォルトのタイムアウトは120秒、間隔は2秒です。ポーリングで受け付け済みの変更が繰り返されることはなく、期限を過ぎて新たな読み取りが開始されることもありません。 すでに実行中のHTTPリクエストには、通常のリクエストタイムアウトが適用されます。

thalovant_list_hub_skill_history（hubId、任意のlimit）で履歴を読み取ります。このツールは読み取り専用モードでも引き続き利用できます。

インベントリのsentence: trueは、読み上げ可能なレンダリングを有効にし、同梱のthalovant-languages 0.2.1のルールを使用して例の大文字表記と句読点を整えます。地域ロケールのマッチングではOVOSの距離を使用します。明示的なslotsはロケールのサンプル値より優先されます。完全なフレーズが先に順位付けされ、exampleLimitは重複のない空でないレンダリング結果の数を指定します。 応答には元のインテント定義がそのまま含まれます。不明なロケールでは、テキストのみが返されます。

CLIは、stdioモードとHTTPモードの両方でSIGTERMとSIGINTを処理します。コンテナのPID 1として実行されている場合も同様です。正常に終了する前にセッションとHTTP接続を閉じます。クリーンアップが停止した場合、失敗とするまでの期限は10秒です。

バージョン0.5.1では、Python 0.7.4と互換性のあるインベントリと質問検出機能を備えたNode SDK 0.7.1を使用します。これにはUnicodeの疑問符と、言語が省略されたパターンが含まれます。sentence: trueの場合、スペイン語の質問には疑問符が付き、完全なフランス語のフレーズには末尾のピリオドが付きます。説明されていない言語では、テキストのみが返されます。