FactVerse MCP — Governed Industrial Tools for AI Agents

Connect AI clients to governed FactVerse tools, industrial data, digital twin context, simulation services, and approved action paths via the Model Context Protocol (MCP).

What is MCP?

Model Context Protocol is an open standard that allows AI applications (such as Claude Desktop, Cursor, self-built Agents) to securely call external tools and data sources.

FactVerse splits its platform tools by the base / module taxonomy into peer governed slices. Each slice is its own endpoint, authenticated by a per-customer API key that resolves to a tenant + scopes:

Slice	Purpose	Capability area
base	General reads + generic compute + cross-cutting actions	Shared asset context, knowledge, documents, data quality, simulation, forecasting, optimization, reviewed action drafts
trafficops (module)	People/vehicle flow operations	Flow context, checkpoints, lanes, roster planning, surge review
pdm (module)	Predictive maintenance	Equipment health context, anomaly review, maintenance planning
telcoops (module)	Telco network operations	Network health, incident context, capacity planning
semiops (module)	Semiconductor / cleanroom / fab / SMT	Cleanroom, utility, facility environment, and SMT operating context

Additional customer-specific slices can be enabled separately when the customer environment includes them.

Quick Integration

Examples below use the base slice (general reads + generic compute). To use a module, swap base in the URL for trafficops / pdm / telcoops / semiops and use a key that holds the matching scope.

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor IDE

In .cursor/mcp.json:

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

Python Client

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

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

            # List the tools this key can see
            tools = await session.list_tools()
            for tool in tools.tools:
                print(f"{tool.name}: {tool.description[:60]}...")

            # Call tool: query equipment status (base.read)
            result = await session.call_tool(
                "get_equipment_status",
                {"equipment_id": "EQ-001"}
            )
            print(result)

            # Run simulation (base.compute.run)
            result = await session.call_tool(
                "run_simulation",
                {
                    "scene_type": "trafficops",
                    "scene_id": "rts-main-hall",
                    "simulation_time": 480
                }
            )
            print(result)

Tool reference workflow

This guide uses runtime tool discovery instead of a fixed tool list. FactVerse MCP tools evolve with product modules and customer environments, so the stable workflow is:

Step	Use
Choose the customer workflow	MCP Capability Guide
Plan endpoint and scope access	MCP Scope Matrix
Prepare source data and governed datasets	Data Fusion Services
List tools visible to the key	Runtime MCP tool discovery from the client
Check current tool names and parameters	MCP Tool Reference
Diagnose access, source-data, compute, or write failures	MCP Errors and Audit

Use the MCP Tool Reference for tool names, descriptions, scopes, and parameters. Use runtime tool discovery for the final availability check in the customer environment.

Capability selection

Need	Start with	Add when reviewed
Read asset, document, or source-data context	`/mcp/base/` with `base.read`	Module endpoint for domain-specific signals.
Run simulation, forecasting, optimization, or spatial analysis	`/mcp/base/` with `base.compute.run`	Engineering review for assumptions and output.
Draft work orders or inspection tasks	`/mcp/base/` with `base.action.write`	Human approval and audit record.
Review predictive maintenance output	`/mcp/pdm/` with `pdm.read`	`/mcp/base/` for asset records and reviewed action drafts.
Review a module-specific operating domain	The enabled module endpoint	`/mcp/base/` for shared documents and asset context.

For workflows that depend on source-system signals, connector health, quality flags, or governed datasets, prepare the data path first with DFS Lite Connectors and DFS Pro Datasets.

Authentication & authorization (key → tenant + scopes)

Every /mcp/<slice> is a governed endpoint: each request is authenticated with a per-customer API key that the server resolves to a tenant and a set of permission scopes. Tenant context and tool access come from the issued key.

Header: X-API-Key: fvk_…
Keys are issued per tenant by an administrator, stored hashed, and shown once.
No key → 403 at the gateway; invalid/revoked key → 401.

Scopes (which tools a key may call)

scope	slice	capability area
`base.read`	base	general reads for assets, knowledge, documents, connectors, data quality, and pending tasks
`base.compute.run`	base	generic compute for simulation, optimization, forecasting, analysis, and spatial workflows
`base.action.write`	base	reviewed action drafts and controlled record creation; requires explicit approval
`trafficops.read`	trafficops	TrafficOps module context for flow, checkpoints, lanes, rosters, and surge review
`pdm.read`	pdm	predictive maintenance module context for equipment health, anomalies, and maintenance planning
`telcoops.read`	telcoops	TelcoOps module context for network health, incidents, and capacity planning
`semiops.read`	semiops	semiconductor, cleanroom, utility, facility environment, and SMT operating context

Modules are isolated: a module key sees only the tools covered by its approved scopes. Grant a single key multiple scopes when cross-slice access is needed.

A tools/call for a tool whose scope the key lacks is refused fail-closed with missing required scope '…'. A key may hold multiple scopes.

Use Cases

1. Claude Reviews a Facility Scenario

User: "How has chiller #7 been running lately? What if we reduce frequency to 42Hz?"

Claude calls:
  → get_equipment_status(equipment_id="CHILLER-007")     # base.read
  → run_simulation(scene_type="fms", config_overrides={"frequency": 42})  # base.compute.run
  → Synthesizes analysis and responds

2. Self-Built Agent Drafts Follow-Up Actions

# Check equipment health hourly (pdm.read); draft a follow-up work order after review (base.action.write)
health = await pdm_session.call_tool("get_equipment_health", {"equipment_name": "critical pump"})

for equipment in health.data["equipment"]:
    if equipment["health_score"] < 60:
        await base_session.call_tool("create_work_order", {
            "equipment_id": equipment["id"],
            "priority": "HIGH",
            "title": "Review low health score",
            "description": f"AI detected health score below 60: {equipment['health_score']}"
        })

3. Query Production Data in Cursor

In Cursor IDE, connect the semiops slice and ask: "How's the particle trend in cleanroom CR-001?" → Cursor calls get_particle_trend via MCP.

Production client requirements

FactVerse MCP is exposed as governed HTTPS endpoints such as /mcp/base/, /mcp/trafficops/, /mcp/pdm/, /mcp/telcoops/, and /mcp/semiops/. The exact endpoint set depends on the modules enabled for the customer environment.

Production clients should use HTTPS, send X-API-Key on every request, and discover available tools at runtime through MCP. The trailing slash form /mcp/<slice>/ is the canonical endpoint shape.

Tenant and scope resolve from the issued key. The platform accepts calls only when the key has the required scope.

Validation checklist

Before a client is used in a customer workflow, confirm:

endpoint URL uses the canonical /mcp/<slice>/ shape;
API key resolves to the intended tenant;
runtime tool discovery lists only the expected tools;
the configured scopes match the approved access package;
source evidence, timestamps, and assumptions appear in the client output;
compute results are reviewed by the named owner;
write actions are drafts until human approval is captured;
errors and refused calls are recorded for audit review.

What is MCP?​

Quick Integration​

Claude Desktop​

Cursor IDE​

Python Client​

Tool reference workflow​

Capability selection​

Authentication & authorization (key → tenant + scopes)​

Scopes (which tools a key may call)​

Use Cases​

1. Claude Reviews a Facility Scenario​

2. Self-Built Agent Drafts Follow-Up Actions​

3. Query Production Data in Cursor​

Production client requirements​

Validation checklist​