> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lucitra.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
# MCP Server
Connect Lucitra Validate to AI coding assistants and agent workflows using the Model Context Protocol (MCP). The Lucitra MCP server exposes validation tools that AI assistants can call directly, enabling natural language interaction with your synthetic data pipeline.
The MCP server uses the **stdio** transport and runs as a local process managed by your MCP client. No ports or network configuration are required.
## Installation
The MCP server is distributed as an npm package. No global installation is needed when using `npx`.
```bash theme={null}
npm install -g @lucitra/mcp
```
| | |
| --------------- | ------------------ |
| **Package** | `@lucitra/mcp` |
| **Server name** | `lucitra-validate` |
| **Version** | 0.1.0 |
| **Transport** | stdio |
## Configuration
Add the following to your `claude_desktop_config.json`:
On macOS this file is located at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows it is at `%APPDATA%\Claude\claude_desktop_config.json`.
```json claude_desktop_config.json theme={null}
{
"mcpServers": {
"lucitra-validate": {
"command": "npx",
"args": ["-y", "@lucitra/mcp"],
"env": {
"LUCITRA_API_KEY": "luci_your_api_key",
"LUCITRA_API_URL": "https://api.lucitra.io"
}
}
}
}
```
Add the server to your project's `.claude/settings.json` or configure it via the CLI:
```json .claude/settings.json theme={null}
{
"mcpServers": {
"lucitra-validate": {
"command": "npx",
"args": ["-y", "@lucitra/mcp"],
"env": {
"LUCITRA_API_KEY": "luci_your_api_key",
"LUCITRA_API_URL": "https://api.lucitra.io"
}
}
}
}
```
Any MCP-compatible client can connect to the Lucitra server. Configure it with:
* **Command**: `npx -y @lucitra/mcp`
* **Transport**: stdio
* **Required env vars**: `LUCITRA_API_KEY`, `LUCITRA_API_URL`
The `LUCITRA_API_KEY` and `LUCITRA_API_URL` environment variables are required. The server will fail to start without them.
## Available Tools
The MCP server exposes five tools that AI assistants can call.
Run a full or targeted validation against a dataset. Polls until the job completes and returns the full report.
Run a coverage-only validation and return a focused summary with scores and details.
Fetch a previously generated validation report by its ID.
Upload a local file as a new dataset. Creates the dataset record and handles the signed URL upload.
List all datasets in a project.
### validate\_dataset
Run a validation job against a dataset. The tool polls for completion and returns the full report.
| Parameter | Type | Required | Description |
| -------------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `datasetId` | string | Yes | UUID of the dataset to validate |
| `type` | enum | No | Validation type: `coverage`, `physics`, `sim-to-real`, `full` (default: `full`) |
| `referenceDatasetId` | string | No | UUID of a reference dataset for sim-to-real comparison |
### check\_coverage
Run a coverage-only validation and return a focused summary.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ---------------------------- |
| `datasetId` | string | Yes | UUID of the dataset to check |
Returns:
```json theme={null}
{
"coverage_score": 78,
"overall_score": 82,
"report_id": "rpt_a1b2c3d4e5f6",
"details": {
"scenario_coverage": 0.85,
"class_coverage": 0.72,
"edge_case_coverage": 0.68
}
}
```
### get\_report
Fetch a complete validation report by its ID.
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------ |
| `reportId` | string | Yes | UUID of the report to retrieve |
### upload\_dataset
Upload a local file to create a new dataset. The tool creates the dataset record and uploads the file via a signed URL.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ----------------------------------------------------- |
| `projectId` | string | Yes | UUID of the target project |
| `name` | string | Yes | Human-readable name for the dataset |
| `format` | enum | Yes | Dataset format: `coco`, `kitti`, `nuscenes`, `custom` |
| `filePath` | string | Yes | Absolute path to the local file |
### list\_datasets
List all datasets in a project.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ------------------- |
| `projectId` | string | Yes | UUID of the project |
## Example Prompts
Once the MCP server is configured, you can interact with Lucitra using natural language in your AI assistant. Here are example prompts:
```
Validate my warehouse dataset ds_x7y8z9a0b1c2 and tell me if
the physics scores are above 85.
```
```
Run a coverage check on dataset ds_x7y8z9a0b1c2 and summarize
what scenarios are missing.
```
```
Run a sim-to-real validation on ds_abc123 using ds_def456 as the
real-world reference dataset.
```
```
Pull up report rpt_a1b2c3d4e5f6 and explain the top 3 issues
I should fix before retraining.
```
```
Compare the coverage scores between my last two validation reports
and tell me if we improved.
```
```
List all datasets in project 9f1a2b3c-4d5e and tell me which
ones have not been validated yet.
```
```
Upload the file at /data/coco-export.json as a new COCO dataset
called "factory-floor-v4" in project 9f1a2b3c.
```
The MCP server returns structured data, so your AI assistant can analyze scores, compare reports, and provide actionable recommendations without you needing to read raw JSON.
## Next Steps
Use the CLI for scripting and CI/CD pipelines.
Access the full REST API for programmatic integration.