Model Context Protocol (MCP)

Veri speaks the Model Context Protocol, so MCP clients such as Claude Code, Claude Desktop, and Cursor can inspect deployment metrics and request failures, query bounded training metrics, check account burn, and—when writes are enabled—submit, cancel, or clean up runs on your behalf. There are two ways to connect, with the same tools either way:

Hosted endpoint (recommended): https://api.veri.studio/mcp — nothing to install, authenticated with your API key.
Local server: veri mcp serve runs as a subprocess of your MCP client and uses your veri login credentials. Use it if you prefer not to place an API key in client config.

Hosted endpoint

Connect with your Veri API key as a bearer header (create one from the dashboard’s API keys page). Every call acts as that key’s owner — the same permissions you have from the CLI, nothing more. Claude Code: put the key in your shell’s environment first, then register the endpoint:

export VERI_API_KEY=vk_...
claude mcp add --transport http veri https://api.veri.studio/mcp \
  --header "Authorization: Bearer $VERI_API_KEY"

Your shell substitutes the key when you run claude mcp add, and Claude Code stores it in its own config. Do not add -s project to this command: that writes the key into a .mcp.json that is usually committed. Cursor takes a URL entry under mcpServers in ~/.cursor/mcp.json (or .cursor/mcp.json in a project). Reference the key as ${env:VERI_API_KEY} rather than pasting it: .cursor/mcp.json is often committed, and Cursor fills the value in from its environment.

{
  "mcpServers": {
    "veri": {
      "url": "https://api.veri.studio/mcp",
      "headers": { "Authorization": "Bearer ${env:VERI_API_KEY}" }
    }
  }
}

Claude Desktop only launches local servers from claude_desktop_config.json (command and args, no url entries), so use the local server there. For an unattended agent, use https://api.veri.studio/readonly/mcp instead: the write and delete tools are not registered at all on that path (see Read-only mode). Verify with /mcp inside a Claude Code session, or ask the agent “what is my Veri credit balance?”

Local server setup

The local server runs on your own machine: your MCP client starts it as a subprocess and talks to it over stdin/stdout, so there is no port to open and no API key in client config — it authenticates with your stored veri login credentials.

Install the SDK with the mcp extra

The MCP server ships with the SDK behind an optional mcp extra. Run this even if veri is already installed: these flags upgrade an existing install and add the extra, which uv tool upgrade and pipx upgrade never do.

uv tool install --upgrade 'veri-sdk[mcp]'

pipx install --force 'veri-sdk[mcp]'

# Python 3.10+ in a virtualenv; the stock macOS python3 is too old
pip install 'veri-sdk[mcp]'

A uv tool or pipx install keeps only the extras named on the latest install: installing 'veri-sdk[attach]' alone removes mcp. Name every extra you use in one install, or take them all with 'veri-sdk[all]' (mcp, attach, yaml, tui). veri doctor reports a failing mcp extra row when veri mcp serve cannot start.

The server reads your stored credentials, so log in once:

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).

Check that the server starts

MCP clients do not show the server’s error output: when veri mcp serve cannot start, Claude Code reports only Failed to connect and Connection closed. Start it once yourself so you can see the reason:

veri mcp serve --readonly </dev/null

It exits with no output when it can start. If it prints an error instead, fix that first: a missing mcp extra means re-running the install line from the first step, and Not logged in means running veri login.

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:

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:

{
  "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

If the client reports that it cannot find veri (desktop apps often start without your shell’s PATH), set "command" to the absolute path that which veri prints.

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 the veri line ends in ✔ 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.

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 12 write and delete tools (every tool in the write and delete tables below) are not registered at all. Pass --readonly in the command:

claude mcp add veri -- veri mcp serve --readonly

{
  "mcpServers": {
    "veri": {
      "command": "veri",
      "args": ["mcp", "serve", "--readonly"]
    }
  }
}

Setting the environment variable VERI_MCP_READONLY=1 has the same effect. On the hosted endpoint, use the /readonly/mcp path instead:

claude mcp add --transport http veri-readonly https://api.veri.studio/readonly/mcp \
  --header "Authorization: Bearer $VERI_API_KEY"

Available tools

Read tools (always available)

Arguments without a default are required. limit values are capped at the maximum shown.

Tool	Arguments	Returns
`veri_whoami`	none	Account identity (`user_id`, `email`, `workspace`), `authenticated: true` and `balance_usd`. With a missing or expired key it returns `authenticated: false` and a `next_step` instead of failing. Call this first.
`veri_list_training_jobs`	`limit` (20, max 100), `status`, `method`	Jobs, newest first.
`veri_get_training_job`	`job_id`	One job: `status`, `method`, `cost_usd`, step and loss progress, `dashboard_url`, `wandb_run_url`, `hf_repo_url`, `error_message` and `error_code` (`CAPACITY_UNAVAILABLE`, `QUOTA_EXCEEDED`, `config_error`, …). While the job runs, `cost_so_far_usd` at `user_rate_per_hour_usd`; and the lifecycle timestamps `created_at`, `launched_at`, `provision_started_at` (billing start), `started_at`, `completed_at` and `terminated_at`.
`veri_get_training_metrics`	`job_id`, `keys`, `from_step`, `to_step`, `max_points` (200, max 500)	`{metrics, available_keys, latest_step}`: sampled native training curves.
`veri_list_deployments`	`limit` (20, max 100), `status`	Deployments, newest first.
`veri_get_deployment`	`deployment_id`	One deployment: `status`, `endpoint_url`, `gpu`, `cost_per_hour_usd`, `error` and `failure_code`.
`veri_get_deployment_summary` / `veri_get_deployment_metrics`	`deployment_id`	`{deployment, metrics}`: lifetime request and token totals, past-24-hour latency percentiles and error rate, uptime and cost. Both return the same shape.
`veri_get_deployment_metrics_timeseries`	`deployment_id`, `from_`, `to` (ISO 8601; default the last seven days), `interval` (`auto`, `minute`, `five_minutes`, `hour` or `day`)	`{summary, buckets, cost_efficiency}` for the range.
`veri_query_deployment_metrics`	`deployment_id`, `from_time`, `to_time`, `interval`, `metrics`	The same, with each bucket cut down to the `metrics` keys you name (plus `timestamp`). At most 500 buckets.
`veri_list_deployment_requests`	`deployment_id`, `limit` (20, max 50), `after`, `errors_only`, `from_time`, `to_time`	Request records, newest first: tokens, latency, TTFT and TPOT, status code and error category.
`veri_chat_deployment`	`deployment_id`, `messages`, `model`, `temperature` (1.0), `max_tokens`	The OpenAI-style chat completion. On the read-only endpoint it never wakes a parked (`scaled_to_zero`) deployment and returns `{status: "scaled_to_zero", choices: [], error: ...}` instead; with writes enabled, chatting to a parked deployment sends the request once, which wakes it (GPU boot, billing starts), and returns `{status: "waking", choices: [], error: "...retry in about Ns..."}` immediately instead of waiting; call the tool again after the hinted delay.
`veri_list_models`	`limit` (20, max 100)	Library models: `id`, `name`, `status`, `base_model`, `training_job_id`, `artifact_type`.
`veri_get_hf_export`	`export_id`	A Hugging Face export: `status` (`launching`, `uploading`, `completed`, `failed` or `cancelled`), progress bytes and `hf_repo_url`.
`veri_list_datasets`	`limit` (20, max 100)	Datasets: `id`, `name`, `source_type`, `huggingface_dataset`.
`veri_list_volumes`	`limit` (20, max 100)	Volumes: `id`, `name`, `total_bytes`, `file_count`.
`veri_list_gpus`	none	The GPU catalog: per provider and workload (`training` or `serving`), each GPU type’s allowed counts (`node_counts`), `status` and `usd_per_gpu_hr`.
`veri_gpu_availability`	`provider`, `gpu_type`, `region`	Live availability per provider, shape and region: `status` (`AVAILABLE`, `OFFERED`, `UNAVAILABLE`) and `price_per_hr`. Check it before a launch, and again after a `CAPACITY_UNAVAILABLE` or `QUOTA_EXCEEDED` failure to pick another shape. Hosted server now; local `veri mcp serve` from the next SDK release.
`veri_list_regions`	none	The launch regions you can target and the default.
`veri_estimate_cost`	`gpu_type`, `gpu_count` (1), `duration_minutes` (60), `provider`	`rate_usd_per_hour` and `estimated_cost_usd`.
`veri_billing_balance`	none	`balance_usd`.
`veri_billing_burn_rate`	none	`burn_rate_usd_per_hour`, `hours_remaining`, and the active jobs and deployments.
`veri_billing_overview` / `veri_get_billing_overview`	`transaction_limit` (10, max 20)	`{balance, burn_rate, transactions}`. Both return the same shape.
`veri_get_cost_summary`	`days` (30, max 30)	Training-job spend for the window: `window_days`, `total_usd`, `job_count`. Deployment spend is not included.
`veri_list_evaluators`	`include_archived` (false)	Evaluators (LLM judge, code, human) with their latest version’s `method`, `scope` and `output_type`, without prompts or source.
`veri_get_experiment`	`experiment_id`	Status (`queued`, `running`, `awaiting_local`, `completed`, `failed` or `canceled`), progress, the pinned evaluator versions, per-evaluator aggregates, the verdict `passed` and the `diff` against its baseline.
`veri_get_model_gate`	`model` (a lineage name)	The lineage’s promotion gate: `enabled`, `config`, production’s latest matching experiment and judge-vs-human agreement warnings.

Write tools (available unless read-only)

Tool	Arguments	Returns
`veri_create_training_job`	`base_model`, `dataset_id`, `gpu_type`, `gpu_count` (1), `output_name` (“default”), `method` (“grpo”), `reward_source`, `hyperparameters`, `region`, `provider`, `hf_push`	`{job, cost_estimate}`. The estimate is for one hour on the chosen GPUs (null if it could not be computed). `grpo` needs `reward_source` (the reward function’s Python source).
`veri_create_deployment`	`model`, `name`, `gpu_type`, `gpu_count` (1), `source` (“training_job”), `provider`, `engine`	The new deployment. `model` is a training job id (`source="training_job"`), a Hugging Face repo (`source="huggingface"`) or a library model id (`source="custom_model"`).
`veri_cancel_training_job`	`job_id`	The cancelled job. A job that already finished returns an error.
`veri_stop_deployment`	`deployment_id`	The deployment. Permanent: a stopped deployment cannot be resumed or woken. Stopping a stopped or failed deployment returns it unchanged.
`veri_register_model`	`training_job_id`, `name`	The library model (same fields as `veri_list_models`). Only a completed job with a saved checkpoint registers; a repeat call returns the existing model.
`veri_push_model_to_hf`	`model_id`, `repo` (“namespace/name”), `private` (true)	The export; poll `veri_get_hf_export` until it finishes. Needs a connected Hugging Face account.
`veri_run_experiment`	`name`, `dataset`, `target`, `evaluators`, `trials`, `baseline_experiment_id`	The queued experiment; poll `veri_get_experiment`. `target` is `{"kind": "deployment", "deployment_id": ...}`, `{"kind": "model_version", "model_version_id": ...}` or `{"kind": "none"}` (score the outputs already in the dataset). Runs on existing deployments, no new GPUs.

Delete tools (available unless read-only)

Deletes are irreversible and, unlike provisioning, cost nothing, so your MCP client’s approval prompt is the only safeguard. Every description below starts with PERMANENTLY DELETES so the stakes are visible in that prompt. Use read-only mode for any unattended agent. Each returns {"deleted": true, "id": ..., "object": ...}.

Tool	Arguments	What it deletes
`veri_delete_training_job`	`job_id`	A finished job and its stored checkpoints.
`veri_delete_dataset`	`dataset_id`	A dataset.
`veri_delete_deployment`	`deployment_id`	A stopped deployment and its request history.
`veri_delete_model`	`model_id`	A library model. Returns an error while an active deployment uses it or a lineage alias points at it.
`veri_delete_volume`	`name`	A volume and every file in it.

Job logs, lifecycle webhooks, Prometheus metrics export, and per-replica drain have no MCP tools today. Read logs with veri jobs logs <id> and reach the rest over REST; see the API reference. Creating evaluators and running local code evaluators happen in the veri CLI (veri evaluators create, veri experiments run --local): an experiment that pins a local code evaluator waits in awaiting_local until those scores arrive.

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:

claude mcp add veri-observe -- veri mcp serve --readonly

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

Inspect deployment <deployment-id> 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:

veri_get_deployment_metrics for compact lifetime health and cost context.
veri_query_deployment_metrics for server-aggregated time-series buckets.
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.

Deployment observability smoke test

Generate buffered and streaming traffic, verify dashboard charts, test SDK and REST queries, and interpret every metric.

Self-hosting the HTTP server

veri mcp serve-http is the multi-tenant streamable HTTP server behind the hosted https://api.veri.studio/mcp endpoint. You can also run it yourself, for example on an internal host shared by a team of agents:

veri mcp serve-http --host 0.0.0.0 --port 8321

The HTTP server does not use your local veri login credentials. Every request must carry your Veri API key as a bearer token, and each call acts as that key’s owner. The server speaks plain HTTP (no TLS), so connect with an http:// URL. Bearer keys travel in every request: beyond a trusted network, put a TLS-terminating proxy in front of it and use the proxy’s https:// URL instead.

claude mcp add --transport http veri http://your-host:8321/mcp \
  --header "Authorization: Bearer $VERI_API_KEY"

{
  "mcpServers": {
    "veri": {
      "url": "http://your-host:8321/mcp",
      "headers": { "Authorization": "Bearer vk_..." }
    }
  }
}

Two endpoints are served:

Path	Tools
`/mcp`	Full surface — write tools gated by your MCP client’s per-call approval, same as stdio.
`/readonly/mcp`	Read tools only. The HTTP analogue of `--readonly` for unattended agents.

The transport is stateless, so the service scales horizontally behind a plain load balancer, and GET /healthz is an unauthenticated liveness probe. Requests are forwarded to the Veri API with the caller’s own key — the server holds no credentials of its own. Point it at a different control plane with --upstream-url or VERI_MCP_UPSTREAM_URL.

Training analysis with W&B

Use Veri MCP for infrastructure, lifecycle, deployment telemetry, and billing. Connect the official W&B MCP alongside it for rich cross-run training analysis, artifacts, and reports. veri_get_training_metrics returns a bounded native metric series, and veri_get_training_job returns the run’s wandb_run_url when the job logged to W&B. Veri does not proxy W&B credentials or reimplement W&B’s query surface.

Working with datasets and rewards

The server does not upload local files. Upload your dataset with the CLI first, then pass its id to the agent:

veri datasets upload ./data/train.jsonl --name my-data

Rewards need no upload step: veri_create_training_job takes a reward_source parameter carrying the reward function’s Python source text, so the agent passes the code inline when it creates the job.

Harness-in-the-loop RL jobs

Harness RL jobs (method grpo_harness, where your own agent, built on the OpenAI SDK, LangChain, or the Anthropic SDK, drives the GRPO rollouts unmodified) are regular training jobs to MCP: they appear in veri_list_training_jobs, veri_get_training_job and veri_get_training_metrics like any other run (read their logs with veri jobs logs <id> and their setup and checkpoint events with veri jobs events <id>). Submission is CLI-only today (veri run-harness, because the harness code directory is uploaded with the job; veri_create_training_job does not accept this method), and the per-rollout trajectory archive lives on the job’s dashboard page. When a user asks their agent how to RL-train the model behind an existing agent or harness, the setup is small enough to explain conversationally: the agent keeps its normal loop and reads OPENAI_BASE_URL / ANTHROPIC_BASE_URL (pointed at the in-training policy per rollout) plus the task from VERI_TASK_INPUT; a TRL-signature reward function (attached to the job inline) scores each finished trajectory. The full contract and a worked demo: Harness-in-the-loop RL and the URL-extraction agent demo.

Get started

Training

Deployments

Evaluations

Agents

CLI

Volumes

Webhooks

Secrets

Billing

Hosted endpoint

Local server setup

Read-only mode

Available tools

Read tools (always available)

Write tools (available unless read-only)

Delete tools (available unless read-only)

Test deployment observability with MCP

Deployment observability smoke test

Self-hosting the HTTP server

Training analysis with W&B

Working with datasets and rewards

Harness-in-the-loop RL jobs

​Hosted endpoint

​Local server setup

​Read-only mode

​Available tools

​Read tools (always available)

​Write tools (available unless read-only)

​Delete tools (available unless read-only)

​Test deployment observability with MCP

Deployment observability smoke test

​Self-hosting the HTTP server

​Training analysis with W&B

​Working with datasets and rewards

​Harness-in-the-loop RL jobs

Hosted endpoint

Local server setup

Read-only mode

Available tools

Read tools (always available)

Write tools (available unless read-only)

Delete tools (available unless read-only)

Test deployment observability with MCP

Self-hosting the HTTP server

Training analysis with W&B

Working with datasets and rewards

Harness-in-the-loop RL jobs