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.

AI client -> /mcp/<slice>/ -> API key resolves tenant and scopes -> allowed tools

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 the current generated catalog.

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`

The retired /mcp/physical/ endpoint is kept only for migration awareness. New Physical AI workflows should use the current base and module endpoints together with Designer scenes, SimReady assets, and simulation workflows.

Configure a client

Every request uses X-API-Key. Do not pass tenant identifiers in a header as a substitute for key-based authorization.

{
  "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 deployment 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 not listed, do not hard-code the call. 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 Designer scene context	Scene version, asset version, simulation assumptions, 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 does not hold the 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 generated tool and scope details.

Prerequisites​

Choose an endpoint​

Configure a client​

Verify the setup​

First workflow checks​

Common startup failures​

Next steps​