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

# Model Context Protocol (MCP)

> Set up a local MCP server so agents can inspect Veri jobs, deployment telemetry, billing, and evals or start approved runs.

`veri mcp serve` runs a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio that exposes Veri as a set of tools. MCP clients such as Claude Code, Claude Desktop, and Cursor can inspect deployment metrics and request failures, query bounded training metrics, check account burn, compare eval runs, and—when writes are enabled—submit or cancel runs on your behalf.

The server runs on your own machine. Your MCP client starts it as a subprocess and talks to it over stdin/stdout, so there is nothing to host and no port to open. It authenticates with the same credentials the CLI uses, so it can do exactly what you can do from the CLI, nothing more.

## Setup

<Steps>
  <Step title="Install the SDK with the mcp extra">
    The MCP server ships with the SDK behind an optional `mcp` extra:

    <CodeGroup>
      ```bash uv (recommended) theme={null}
      uv tool install 'veri-sdk[mcp]'
      ```

      ```bash pipx theme={null}
      pipx install 'veri-sdk[mcp]'
      ```

      ```bash pip theme={null}
      pip install 'veri-sdk[mcp]'
      ```
    </CodeGroup>

    Confirm the command is available:

    ```bash theme={null}
    veri mcp serve --help
    ```
  </Step>

  <Step title="Log in">
    The server reads your stored credentials, so log in once:

    ```bash theme={null}
    veri login
    ```

    You never paste an API key into the MCP client. The server uses the credentials from `veri login` (or the `VERI_API_KEY` environment variable if you set one).
  </Step>

  <Step title="Register Veri in your client">
    Add Veri to your MCP client. The command the client runs is always `veri mcp serve`.

    **Claude Code** has a one-liner. The part after `--` is the command it will spawn:

    ```bash theme={null}
    claude mcp add veri -- veri mcp serve
    ```

    By default this registers Veri for you in the current project. Use `-s user` to make it available in every project, or `-s project` to write a `.mcp.json` that your whole team shares (each teammate still runs their own `veri login`).

    **Claude Desktop** and **Cursor** are configured with a JSON file. Add a `veri` entry under `mcpServers`:

    ```json theme={null}
    {
      "mcpServers": {
        "veri": {
          "command": "veri",
          "args": ["mcp", "serve"]
        }
      }
    }
    ```

    The file location depends on the client:

    | Client                   | Config file                                                       |
    | ------------------------ | ----------------------------------------------------------------- |
    | Claude Desktop (macOS)   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     |
    | Cursor (global)          | `~/.cursor/mcp.json`                                              |
    | Cursor (per project)     | `.cursor/mcp.json` in the project root                            |
  </Step>

  <Step title="Restart and verify">
    Restart the client so it picks up the new server.

    In Claude Code, run `claude mcp list` (or `/mcp` inside a session) and confirm `veri` shows as connected. In Claude Desktop and Cursor, the Veri tools appear once the server connects. Ask the agent something like "what is my Veri credit balance?" to confirm it can reach your account.
  </Step>
</Steps>

## Read-only mode

By default every tool is available, including ones that create billable GPU jobs and deployments. Your MCP client prompts you to approve each tool call, so creation is gated by that approval. Tools that spend credits have descriptions that begin with `CREATES A BILLABLE ...` so the intent is clear in the approval prompt.

For an automated or unattended setup where no human approves each call, run the server read-only so the creation and cancellation tools are not registered at all. Pass `--readonly` in the command:

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add veri -- veri mcp serve --readonly
  ```

  ```json Claude Desktop / Cursor theme={null}
  {
    "mcpServers": {
      "veri": {
        "command": "veri",
        "args": ["mcp", "serve", "--readonly"]
      }
    }
  }
  ```
</CodeGroup>

Setting the environment variable `VERI_MCP_READONLY=1` has the same effect.

## Available tools

### Read tools (always available)

| Tool                                        | What it does                                                                                  |
| ------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `veri_list_training_jobs`                   | List training jobs, with optional status and method filters.                                  |
| `veri_get_training_job`                     | Get one job: status, cost, dashboard URL, and any error.                                      |
| `veri_list_deployments`                     | List deployments, with an optional status filter.                                             |
| `veri_get_deployment`                       | Get one deployment: status, endpoint, GPU, and running cost.                                  |
| `veri_get_deployment_metrics`               | Get compact lifetime request, token, percentile latency, error, uptime, and cost metrics.     |
| `veri_query_deployment_metrics`             | Query up to 500 server-aggregated metric buckets for a time range (seven days by default).    |
| `veri_list_deployment_requests`             | List compact request telemetry, optionally restricted to failures or a time range.            |
| `veri_get_training_metrics`                 | Get bounded native training curves and the W\&B run URL when available.                       |
| `veri_list_models`                          | List custom models in your registry.                                                          |
| `veri_list_datasets`                        | List datasets available for training.                                                         |
| `veri_list_regions`                         | List the launch regions you can target.                                                       |
| `veri_estimate_cost`                        | Estimate the cost of a GPU job before submitting it.                                          |
| `veri_billing_balance`                      | Get your current credit balance.                                                              |
| `veri_get_billing_overview`                 | Get balance, training and deployment burn, runway, active resources, and recent transactions. |
| `veri_get_cost_summary`                     | Get the supported historical cost breakdown for up to 30 days.                                |
| `veri_list_benchmarks`                      | List the curated benchmark catalog.                                                           |
| `veri_list_evals` / `veri_get_eval`         | List or inspect evaluation definitions.                                                       |
| `veri_list_eval_runs` / `veri_get_eval_run` | List or inspect evaluation runs, results, usage, and gates.                                   |
| `veri_list_eval_run_items`                  | Inspect bounded per-item outputs and scores.                                                  |
| `veri_compare_eval_runs`                    | Compare a candidate eval run with its baseline.                                               |
| `veri_chat_deployment`                      | Send a chat request to a running deployment.                                                  |

### Write tools (available unless read-only)

| Tool                       | What it does                                                                   |
| -------------------------- | ------------------------------------------------------------------------------ |
| `veri_create_training_job` | Submit a managed training run. Returns the job and a pre-submit cost estimate. |
| `veri_create_deployment`   | Create an inference deployment from a training job or a HuggingFace model.     |
| `veri_cancel_training_job` | Cancel a queued or running job.                                                |
| `veri_stop_deployment`     | Stop a running deployment.                                                     |
| `veri_register_model`      | Register a completed job's checkpoint as a reusable custom model.              |
| `veri_create_eval`         | Create an evaluation definition.                                               |
| `veri_start_eval_run`      | Start a billable evaluation run after confirming model and sample count.       |
| `veri_cancel_eval_run`     | Cancel an evaluation run.                                                      |
| `veri_rescore_eval_run`    | Rescore stored outputs; paid model scorers may incur cost.                     |

## Test deployment observability with MCP

MCP is optional for deployment observability—the dashboard, SDK, and REST API expose the same underlying telemetry. MCP is the agent-facing interface for investigating that telemetry in natural language.

For a safe test, register the server in read-only mode:

```bash theme={null}
claude mcp add veri-observe -- veri mcp serve --readonly
```

Send a buffered and a streaming request to a serving deployment, then ask:

> Inspect deployment `dep_...` over the past hour. Report request volume, p50/p95/p99 TTFT and end-to-end latency, token throughput, error rate, and cost efficiency. List failed requests grouped by error category. Do not modify resources.

The agent should use:

1. `veri_get_deployment_metrics` for compact lifetime health and cost context.
2. `veri_query_deployment_metrics` for server-aggregated time-series buckets.
3. `veri_list_deployment_requests` for the terminal records behind errors.

Time-series queries return at most 500 buckets, and request-history queries return at most 50 rows per call. Pass an explicit deployment ID and time window when you want repeatable results.

<Card title="Deployment observability smoke test" icon="chart-line" href="/deployments/observability">
  Generate buffered and streaming traffic, verify dashboard charts, test SDK and REST queries, and interpret every metric.
</Card>

## Training analysis with W\&B

Use Veri MCP for infrastructure, lifecycle, deployment telemetry, billing, and eval comparisons. Connect the official W\&B MCP alongside it for rich cross-run training analysis, artifacts, and reports.

Veri returns a bounded native training metric series and the W\&B run URL when available. It does not proxy W\&B credentials or reimplement W\&B's query surface.

## Working with datasets and reward functions

The server does not upload local files. Upload your dataset and reward functions with the CLI first, then pass their ids to the agent:

```bash theme={null}
veri datasets upload ./data/train.jsonl --name my-data
veri rewards upload ./reward.py --name my-reward
```

The agent can then reference `my-data` and the reward id when it calls `veri_create_training_job`.