> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verial.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Give AI agents direct access to Verial's simulation platform.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard for connecting AI agents to external data sources and tools. Instead of building custom integrations, MCP lets agents call structured tools to query, create, and manage resources in real time. Claude, ChatGPT, Cursor, and any MCP-compatible client can connect to an MCP server and use its tools as part of their reasoning.

## Why MCP for Verial?

Healthcare AI agents need to validate their own behavior against realistic simulated systems. The Verial MCP server gives agents direct access to the simulation platform, so they can set up test environments, run benchmarks, and analyze results without human intervention.

* **Self-testing agents.** An agent can create its own test environment, define benchmarks, execute runs, and review results, all through tool calls in a single conversation.
* **IDE integration.** Connect Verial to Claude, Cursor, or VS Code to manage simulations interactively while developing your agent.
* **Agentic CI/CD.** Chain simulation setup, execution, and result analysis into automated pipelines that run on every deploy.

## Design Principles

<CardGroup cols={2}>
  <Card title="Action-Oriented Tools" icon="bolt">
    Each tool maps to a resource and takes an `action` parameter to select the operation. One tool call to create, update, list, or delete. No multi-step discovery required.
  </Card>

  <Card title="Consistent Interface" icon="equals">
    Every tool follows the same pattern: `action` plus resource-specific fields. Learn one tool and you know them all. Agents can generalize across the entire surface.
  </Card>

  <Card title="Full Platform Access" icon="grid-2">
    Every resource type is available: environments, simulators, datasets, benchmarks, tasks, criteria, playgrounds, sandboxes, benchmark runs, task runs, and criterion runs. Nothing is hidden behind a separate API.
  </Card>

  <Card title="Organization Scoped" icon="building">
    Every tool call is scoped to the authenticated organization. Agents see only the resources they own. No project IDs or tenant parameters to manage.
  </Card>
</CardGroup>

## Tools

One tool per resource. Each tool takes an `action` field to select the operation.

| Tool                                          | Actions                                                            | Description                          |
| --------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------ |
| [`environments`](/mcp/tools/environments)     | list, create, get, update, delete, addSimulator, removeSimulator   | Manage simulated health systems      |
| [`simulators`](/mcp/tools/simulators)         | list, create, get, update, delete                                  | Manage simulator definitions         |
| [`datasets`](/mcp/tools/datasets)             | list, create, get, update, delete                                  | Manage synthetic patient data        |
| [`benchmarks`](/mcp/tools/benchmarks)         | list, create, get, update, delete                                  | Manage benchmark definitions         |
| [`tasks`](/mcp/tools/tasks)                   | list, create, get, update, delete                                  | Manage test cases within benchmarks  |
| [`criteria`](/mcp/tools/criteria)             | list, create, get, update, delete                                  | Manage typed assertions on tasks     |
| [`playgrounds`](/mcp/tools/playgrounds)       | list, create, get, teardown                                        | Provision live environment instances |
| [`sandboxes`](/mcp/tools/sandboxes)           | list, create, get, listEvents, teardown, addDataset, removeDataset | Manage running simulator instances   |
| [`benchmark_runs`](/mcp/tools/benchmark-runs) | list, create, get, complete, cancel                                | Execute benchmarks and track results |
| [`task-runs`](/mcp/tools/task-runs)           | list, get, complete, cancel                                        | Task-level run results               |
| [`criterion-runs`](/mcp/tools/criterion-runs) | list, get                                                          | Per-criterion run results            |

## Data Model

```mermaid theme={null}
graph TD
  SIM["Simulator"]:::resource --> ENV["Environment"]:::resource
  DS["Dataset"]:::resource --> SBX["Sandbox"]:::resource
  ENV --> PG["Playground"]:::resource
  PG --> SBX
  ENV --> BM["Benchmark"]:::resource
  BM --> TASK["Task"]:::resource
  TASK --> CRIT["Criterion"]:::resource
  BM --> RUN["Run"]:::resource
  RUN --> TR["Task Run"]:::resource
  TR --> CR["Criterion Run"]:::resource

  classDef resource fill:#2563eb,color:#fff,stroke:#1d4ed8
```

* **Simulators** define simulated systems (FHIR, HL7, Voice, Fax, Web portals)
* **Environments** compose simulators into a coherent health system
* **Datasets** contain FHIR bundles or files, linked to sandboxes at runtime
* **Benchmarks** group tasks with criteria into a test suite
* **Playgrounds** are running instances of environments with live sandboxes
* **Benchmark runs** execute benchmarks, producing task runs and criterion runs with scores from the verification engine

## Next Steps

<CardGroup cols={2}>
  <Card title="Setup" icon="plug" href="/mcp/setup">
    Connect the Verial MCP server to Claude, ChatGPT, Cursor, or your custom agent.
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/mcp/tools/environments">
    Full parameter and response documentation for each tool.
  </Card>

  <Card title="Workflow Examples" icon="route" href="/mcp/workflows/environment-setup">
    Step-by-step tool call sequences for common simulation tasks.
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/mcp/best-practices">
    Prompt tips, context management, and error handling.
  </Card>
</CardGroup>