Getting Started with FactVerse AI Agent

This guide is for implementation engineers, partners, and customer technical teams who need to connect an AI client to FactVerse AI Agent for the first time.

FactVerse AI Agent uses governed MCP endpoints. A client connects to one endpoint, sends an API key, lists the tools allowed for that key, then calls read or compute tools inside the tenant and scope resolved by the platform.

Prerequisites

Before connecting a client, prepare the following:

Requirement	Notes
FactVerse host	Use the customer or project host provided for the environment. Examples use `https://your-factverse-host`.
MCP endpoint	Use the slice endpoint enabled for the customer, such as `/mcp/base/` or `/mcp/pdm/`.
API key	The key is issued by an administrator, shown once, and sent as `X-API-Key`.
Scopes	The key must hold the scopes required by the tools it will call.
Source data	Asset records, operational signals, documents, scenes, or work-order records must exist before the Agent can reason over them.
MCP-compatible client	Claude Desktop, Cursor, a custom MCP client, or an enterprise agent runtime.

Choose an endpoint

Start with the endpoint that matches the workflow. Use the scope reference for endpoint and permission planning.

Endpoint	Typical use	Common scopes
`/mcp/base/`	General asset reads, knowledge, documents, data quality, simulation, optimization, and approved write actions	`base.read`, `base.compute.run`, `base.action.write`
`/mcp/pdm/`	Predictive maintenance health, summaries, anomalies, and component intelligence	`pdm.read`
`/mcp/trafficops/`	People, vehicle, checkpoint, and traffic operation tools	`trafficops.read`
`/mcp/telcoops/`	Network operation and capacity analysis tools	`telcoops.read`
`/mcp/semiops/`	Cleanroom, fab, utility, SMT, and environment tools	`semiops.read`
`/mcp/aviation/`	Aviation reliability analysis tools	`aviation.analysis.read`

Physical AI workflows use the current base and module endpoints together with scenes, simulation-ready asset packages, DFS-prepared operating data, and simulation workflows.

Configure a client

Every request uses X-API-Key. The platform resolves tenant context from the issued key.

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

Use a separate server entry for each endpoint when the integration needs multiple slices. A single key may hold multiple scopes if the customer access policy allows it.

Verify the setup

Run these checks before building a workflow.

Connect to the endpoint over HTTPS.
Initialize the MCP session.
List tools at runtime.
Confirm the expected tools are visible.
Call a read-only tool first.
Record the response, source references, and any missing data notes.

Python client example:

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)

If the tool is absent from runtime discovery, check the endpoint, key, scope, and module enablement first.

First workflow checks

Workflow	Start with	Verify
Facility operations	`/mcp/base/` with `base.read`	Asset identity, location, status, source-system freshness, and related documents.
Predictive maintenance	`/mcp/pdm/` with `pdm.read`	Equipment health, anomaly visibility, maintenance history, and signal quality.
Physical AI	`/mcp/base/` with `base.compute.run` plus scene and asset context	Scene version, model asset version, component geometry, simulation assumptions, runtime parameters, and validation records.

Write actions such as work-order creation require an explicit write scope such as base.action.write. They should remain behind human approval and audit controls.

Common startup failures

Symptom	Likely cause	Check
`403` at gateway	No API key was sent	Confirm the `X-API-Key` header is present.
`401`	Key is invalid, revoked, or for a different environment	Request a new key from the administrator.
`missing required scope`	Key lacks the required tool scope	Compare the visible tools with the scope reference.
Tool is not listed	Wrong endpoint, module not enabled, or insufficient scope	Use runtime `tools/list` and check the endpoint path.
Empty or weak answer	Source data is missing, stale, or not mapped to the asset	Check DFS pipelines, Platform asset records, Inspector records, and documents.
Write action blocked	Write scope or approval policy is missing	Keep the action as a draft and route it to an approved operator.

Next steps

Read Core Concepts before designing a workflow.
Use the MCP Integration Guide for client-specific configuration.
Use the Tool Reference and Scope Reference for current tool and scope details.

Prerequisites​

Choose an endpoint​

Configure a client​

Verify the setup​

First workflow checks​

Common startup failures​

Next steps​