FactVerse MCP — Physical AI Tools for Any AI Agent

Expose FactVerse's physical world tools to any AI Agent 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	Example tools
base	General reads + generic compute + cross-cutting actions	Equipment status, knowledge query, simulation, optimization, forecasting, create work order
trafficops (module)	People/vehicle flow operations	Traffic forecast, checkpoint lanes, patrol scheduling, surge detection
pdm (module)	Predictive maintenance	Equipment health, predictive maintenance summary/anomalies, filter intelligence
telcoops (module)	Telco network operations	Network health, incident explanation, capacity forecast
semiops (module)	Semiconductor / cleanroom / fab / SMT	Cleanroom status, particle/pressure, HEPA filter life, ISO 14644 compliance, fab PUE, SMT OEE

Additional customer-specific slices can be enabled separately when the deployment contract 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 Categories (by slice)

base — general reads · scope `base.read`

Tool Name	Description
`get_equipment_status`	Get real-time equipment status and sensor readings
`query_knowledge`	Query knowledge graph (equipment/faults/relationships)
`search_documents`	Document search
`get_equipment_documents`	Equipment-related documents
`list_connectors`	Data connector list
`check_data_quality`	Data quality check
`get_pending_tasks`	Get pending approval tasks (read-only)

base — generic compute (simulation/optimization/forecasting/analysis/spatial) · scope `base.compute.run`

Tool Name	Description
`run_simulation`	Run DES simulation (traffic/HVAC/equipment)
`run_doe`	Run design of experiments (identify key factors)
`run_dag_simulation`	DAG checkpoint simulation + Sankey analysis
`run_what_if_comparison`	A/B scenario What-If comparison
`run_optimization`	NSGA-II multi-objective optimization
`optimize_layout`	Facility spatial layout optimization
`get_optimization_recommendation`	Optimal personnel allocation under budget constraints

base — execution (write) · scope `base.action.write` (not granted by default)

Tool Name	Description
`create_work_order`	Create work order from AI recommendation

pdm — predictive maintenance · scope `pdm.read`

Tool Name	Description
`get_equipment_health`	Equipment health score
`get_pdm_summary`	predictive maintenance overview
`list_pdm_anomalies`	predictive maintenance anomaly list

semiops — semiconductor / cleanroom / fab / SMT · scope `semiops.read`

Tool Name	Description
`get_cleanroom_status`	Cleanroom environment status
`get_particle_trend`	Particle trend
`get_pressure_gradient`	Pressure gradient
`get_fab_pue`	Factory PUE value
`get_filter_life`	HEPA filter lifespan
`get_iso_compliance`	ISO 14644 compliance status
`get_smt_oee`	SMT line OEE
`get_utility_status`	Utility (CDA/N2/water/power) status
`analyze_env_correlation`	Environmental parameter correlation analysis
`monitor_particles`	Real-time particle monitoring
`predict_env_trend`	Environment trend prediction
`simulate_smt_bottleneck`	SMT line bottleneck simulation
`forecast_fab_load`	Fab load forecast
`optimize_chiller_cop`	Chiller COP optimization

trafficops / telcoops tool sets are visible via each slice's tools/list.

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 — the client never passes a tenant and cannot use a shared key.

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

Scopes (which tools a key may call)

scope	slice	tools
`base.read`	base	general reads (equipment status, knowledge query, documents, connectors, data quality, pending tasks)
`base.compute.run`	base	generic compute (simulation, optimization, forecasting, analysis, spatial — tenant-agnostic)
`base.action.write`	base	execution tools (create work orders, etc.; not granted by default)
`trafficops.read`	trafficops	TrafficOps module tools (traffic forecast, checkpoint lanes, patrol scheduling, etc.)
`pdm.read`	pdm	predictive maintenance module tools (equipment health, predictive maintenance summary/anomalies, filter intelligence, etc.)
`telcoops.read`	telcoops	TelcoOps module tools (network health, incident explanation, capacity forecast)
`semiops.read`	semiops	semiconductor/cleanroom tools (cleanroom, particle/pressure, HEPA filter, ISO 14644, fab PUE, utilities, SMT OEE/defect classification)

Modules are isolated: a trafficops key cannot call pdm/telcoops/semiops tools, nor base tools. 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 Directly Controls Facility

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 Automates Operations

# Check equipment health hourly (pdm.read); auto-open a work order on low scores (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.

Public deployment 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.

The client should not pass tenant identifiers. The platform resolves tenant and scope from the issued key and refuses calls that require scopes the key does not hold.

What is MCP?​

Quick Integration​

Claude Desktop​

Cursor IDE​

Python Client​

Tool Categories (by slice)​

base — general reads · scope base.read​

base — generic compute (simulation/optimization/forecasting/analysis/spatial) · scope base.compute.run​

base — execution (write) · scope base.action.write (not granted by default)​

pdm — predictive maintenance · scope pdm.read​

semiops — semiconductor / cleanroom / fab / SMT · scope semiops.read​

Authentication & authorization (key → tenant + scopes)​

Scopes (which tools a key may call)​

Use Cases​

1. Claude Directly Controls Facility​

2. Self-Built Agent Automates Operations​

3. Query Production Data in Cursor​

Public deployment requirements​