FactVerse AI Agent はじめに

このガイドは、AI クライアントを初めて FactVerse AI Agent に接続する実装エンジニア、パートナー、顧客技術チーム向けです。

FactVerse AI Agent は管理された MCP endpoint を使用します。クライアントは endpoint に接続し、API key を送信し、その key で利用できるツールを一覧し、プラットフォームが解決したテナントと scope の範囲で read または compute ツールを呼び出します。

AI client -> /mcp/<slice>/ -> API key が tenant と scope を解決 -> 利用可能なツール

前提条件

クライアントを接続する前に、次を準備します。

要件	説明
FactVerse ホスト	顧客またはプロジェクト環境に提供されたホストを使用します。例では `https://your-factverse-host` を使用します。
MCP endpoint	顧客で有効化されている slice endpoint を使用します。例: `/mcp/base/`、`/mcp/pdm/`。
API key	Key は管理者が発行し、一度だけ表示され、`X-API-Key` で送信します。
Scope	Key は呼び出すツールに必要な scope を持っている必要があります。
参照元データ	Agent が推論する前に、アセット記録、運用シグナル、文書、シーン、ワークオーダー記録が必要です。
MCP 対応クライアント	Claude Desktop、Cursor、独自 MCP client、またはエンタープライズ Agent runtime。

endpoint を選ぶ

ワークフローに合う endpoint から始めます。現在のツールと scope は、このサイトで生成された scope reference を基準にします。

Endpoint	主な用途	一般的な scope
`/mcp/base/`	一般的なアセット read、知識、文書、データ品質、シミュレーション、最適化、管理された write action	`base.read`, `base.compute.run`, `base.action.write`
`/mcp/pdm/`	予知保全の健康度、サマリー、異常、コンポーネントインテリジェンス	`pdm.read`
`/mcp/trafficops/`	人流、車両、チェックポイント、交通運用ツール	`trafficops.read`
`/mcp/telcoops/`	ネットワーク運用と容量分析ツール	`telcoops.read`
`/mcp/semiops/`	クリーンルーム、ファブ、utility、SMT、環境ツール	`semiops.read`
`/mcp/aviation/`	航空信頼性分析ツール	`aviation.analysis.read`

廃止済みの /mcp/physical/ endpoint は移行認識のためだけに残されています。新しい Physical AI ワークフローでは、現在の base と module endpoint を使用し、Designer シーン、SimReady asset、シミュレーションフローと組み合わせます。

クライアントを設定する

すべてのリクエストで X-API-Key を使用します。テナント識別子を header で送信して key 認可の代わりにしないでください。

{
  "mcpServers": {
    "factverse-base": {
      "url": "https://your-factverse-host/mcp/base/",
      "headers": {
        "X-API-Key": "fvk_your_scoped_key"
      }
    }
  }
}

複数の slice が必要な場合は、endpoint ごとに別の server entry を設定します。デプロイポリシーが許可する場合、1 つの key が複数の scope を持つことがあります。

接続を検証する

ワークフローを作る前に、次を確認します。

HTTPS で endpoint に接続する。
MCP session を初期化する。
実行時にツールを一覧する。
期待するツールが見えることを確認する。
まず read-only ツールを呼び出す。
レスポンス、参照元、欠落データの注記を記録する。

Python クライアント例：

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client(
        "https://your-factverse-host/mcp/base/",
        headers={"X-API-Key": "fvk_your_scoped_key"},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            for tool in tools.tools:
                print(tool.name)

            result = await session.call_tool(
                "get_equipment_status",
                {"equipment_id": "EQ-001"},
            )
            print(result)

ツールが一覧にない場合は、呼び出しをハードコードしないでください。まず endpoint、key、scope、module の有効化状態を確認します。

最初のワークフローチェック

ワークフロー	開始点	確認内容
施設運用	`/mcp/base/` と `base.read`	アセット ID、場所、状態、参照元システムの鮮度、関連文書。
予知保全	`/mcp/pdm/` と `pdm.read`	設備健康度、異常の可視性、保全履歴、シグナル品質。
Physical AI	`/mcp/base/` と `base.compute.run`、Designer シーンコンテキスト	シーンバージョン、アセットバージョン、シミュレーション仮定、検証記録。

ワークオーダー作成などの write action には、base.action.write のような明示的な write scope が必要です。これらの操作は、人による承認と監査制御の下に置く必要があります。

よくある初期エラー

症状	想定原因	確認
gateway で `403`	API key が送信されていない	`X-API-Key` header があるか確認する。
`401`	Key が無効、失効済み、または別環境用	管理者に新しい key を依頼する。
`missing required scope`	Key が必要な tool scope を持っていない	表示された tools と scope reference を比較する。
ツールが一覧にない	endpoint が違う、module が未有効、または scope 不足	実行時 `tools/list` と endpoint path を確認する。
回答が空または弱い	参照元データが欠落、古い、またはアセットに未マップ	DFS pipeline、Platform アセット記録、Inspector 記録、文書を確認する。
write action がブロックされる	write scope または承認ポリシーがない	操作をドラフトとして残し、承認済みオペレーターに回す。

次のステップ

ワークフロー設計前にコアコンセプトを読む。
クライアント設定には MCP 接続ガイドを使用する。
現在生成されたツールと scope の詳細はツールリファレンスと Scope リファレンスを確認する。

前提条件​

endpoint を選ぶ​

クライアントを設定する​

接続を検証する​

最初のワークフローチェック​

よくある初期エラー​

次のステップ​