MCP tools reference

The Valkyrie MCP server exposes the tools below, grouped by area. Tool names and availability evolve, so your client’s live tool list is always the source of truth, use this page to understand what each does.

Tools marked ⚠ mutating change real resources. Some spend from your wallet or tear down running infrastructure, and act on whatever environment your key points at. There is no undo for a terminate. See what it can’t do.

Server

Tool	What it does
`server_info`	Server information and your authentication status. Works without a key. “Configured” reflects only the key sent with the current request. It doesn’t fall back to a server-side key. “Configured” also only means a key was supplied, call a data tool like `list_deployments` to confirm it’s valid.

Deployments, inspect

Tool	What it does
`list_deployments`	List your model deployments and their status, with why each one is not running (`stop_reason`), when it next starts by itself (`next_scheduled_start_at`) and its schedule in one line (`run_schedule`).
`get_deployment_status`	Detailed status for one deployment: state, health, endpoint, what a starting deployment is doing (with download progress), the boot timeline, for a failed one its failure code and next step, and the same `stop_reason`, `next_scheduled_start_at` and `run_schedule` as the list.
`get_endpoint_connection`	How to connect a client to one deployment: its base URL and alias URLs, whether it runs now (`is_running`), the model name to send, its state and schedule, and snippets for OpenAI-compatible clients such as Opencode (with a placeholder key).
`create_endpoint_key`	⚠ mutating Create a key scoped to one deployment, for anyone who may use it. The key value is returned once.
`diagnose_deployment`	Everything `get_deployment_status` returns, plus the last start-up report from the machine and the tail of its stored logs (`tail_lines`, default 60, max 300). Read-only: it changes nothing. See Diagnose a deployment.
`check_deployment_health`	Actively health-check a deployment’s model.
`check_service_health`	Check the underlying serving service (engine/process) health.

Deployments, create & lifecycle

Tool	What it does
`deploy_base_model`	⚠ mutating Deploy any Hugging Face base model to a new serving endpoint. Optional: `capacity` (`on_demand` or `interruptible`), `placement_policy`, `always_on`, `idle_stop_minutes`, and `dry_run=true` to run the pre-deploy checks without renting a GPU. See Deploy options.
`deploy_fine_tuned_model`	⚠ mutating Deploy a completed fine-tuning job’s model. Takes `always_on` or `idle_stop_minutes`.
`start_model_service`	⚠ mutating Start the serving process on a deployment.
`restart_model_service`	⚠ mutating Restart just the serving process (no redeploy).
`restart_deployment`	⚠ mutating Restart the whole deployment.
`stop_deployment`	⚠ mutating Stop a deployment and release its GPU.
`pause_deployment`	⚠ mutating Pause a deployment.
`resume_deployment`	⚠ mutating Resume a paused/stopped deployment (re-provisions a GPU).
`recover_failed_deployment`	⚠ mutating Attempt to recover a deployment stuck in a failed state.
`resync_deployment_instance`	Re-sync a deployment’s record with its actual cloud instance.
`set_deployment_always_on`	⚠ mutating Turn always-on on or off. On: idle stops and stop schedules skip the deployment, a lost GPU is replaced, and a pending one-off scheduled stop is cleared. Off: nothing stops now; the idle stop applies again from now. Refused for an ended deployment.
`set_deployment_idle_stop`	⚠ mutating Set a deployment’s own idle timeout (`idle_stop_minutes`, 30 to 1440), or pass `null` to go back to the platform default. The idle clock restarts from now. Returns `idle_stop_minutes`, `is_custom`, and `stops_at`. Refused with `409` for an ended deployment, and for a value on an always-on one. Start a deployment again after an idle stop with `resume_deployment`.
`execute_tool`	Run a deployed model (`deployment-{id}`) or the fine-tune control plane (`fine-tuning` / `fine-tuned-{job_id}`).

Deployments, schedules & auto-recovery

Tool	What it does
`get_deployment_schedules`	List schedules configured for a deployment.
`set_deployment_schedule`	⚠ mutating Set a custom cron start/stop schedule.
`configure_deployment_12h_schedule`	⚠ mutating Apply a preset 12-hour uptime schedule.
`configure_deployment_auto_restart`	⚠ mutating Enable/configure automatic restart when unhealthy.
`set_deployment_scheduled_stop`	⚠ mutating Schedule a one-off stop.
`clear_deployment_scheduled_stop`	⚠ mutating Clear a scheduled stop.
`set_deployment_scheduled_restart`	⚠ mutating Schedule a one-off restart.
`clear_deployment_scheduled_restart`	⚠ mutating Clear a scheduled restart.
`toggle_deployment_schedule`	⚠ mutating Enable or disable a schedule.
`trigger_deployment_schedule`	⚠ mutating Run a schedule’s action immediately.
`delete_deployment_schedule`	⚠ mutating Delete a schedule.
`list_deployment_schedule_executions`	List a schedule’s past executions.

Deploy options

deploy_base_model takes these options on top of the model and serving settings:

Option	Values	What it does
`capacity`	`on_demand` (default), `interruptible`	Interruptible capacity is cheaper, but the GPU can be taken back when someone outbids it. The deployment then shows Interrupted (outbid). See Interruptible capacity.
`placement_policy`	`cost_to_ready` (default), `lowest_price`	`cost_to_ready` weighs the hourly price against how long the machine is likely to take to serve. `lowest_price` takes the cheapest machine that fits.
`always_on`	`true`, `false` (default)	Keep the deployment up around the clock. Can’t be combined with `scheduled_stop_at`. See Always-on endpoints.
`idle_stop_minutes`	30 to 1440	Pay as you go: stop the deployment after this many minutes without inference requests. Leave it out for the platform default (2 hours). Can’t be combined with `always_on`. Also taken by `deploy_fine_tuned_model`.
`dry_run`	`true`, `false` (default)	Run the pre-deploy checks (configuration, the Hugging Face repository and its weight files) and return the report without renting a GPU. A real deploy runs the same checks and fails before renting on any error.

The model name must be a Hugging Face repository id in owner/name form. Anything else is refused before a GPU is rented. See Model names.

Fine-tuning, jobs

Tool	What it does
`list_fine_tuning_jobs`	List your fine-tuning jobs.
`get_fine_tuning_job`	One job’s details and status.
`create_fine_tuning_job`	⚠ mutating Create and launch a new fine-tuning job. `capacity="interruptible"` trains on cheaper capacity that can be interrupted; see Interruptible capacity. `eval_checks` scores the held-back test; see Eval checks. For a catalog model, the wallet must cover the estimate plus a buffer; see Balance check.
`retry_fine_tuning_job`	⚠ mutating Retry a job (reschedule onto fresh hardware).
`cancel_fine_tuning_job`	⚠ mutating Cancel a running or pending job.
`recover_failed_job`	⚠ mutating Recover a job stuck in a failed state.
`list_fine_tuning_models`	List models produced by completed jobs.
`terminate_cluster`	⚠ mutating Terminate the GPU cluster backing a job.

Eval checks

create_fine_tuning_job takes eval_checks: up to 10 checks to score the held-back answers with, one per kind, each with an optional target (0 to 100, the lowest share of answers in percent that must pass). Call suggest_eval_checks(dataset_id) for the checks that fit a dataset, then pass the ones you want without their label and suggested fields.

Kind	Setting it needs
`valid_json`	None
`json_schema`	`json_schema`: the JSON Schema answers must match (up to 10 KB)
`within`	`tolerance`, with `tolerance_unit` `percent` (default) or `absolute`
`label_accuracy`	None
`latency`	`max_ms`: the slowest answer that passes

{
  "dataset_id": "ds-123",
  "model_name": "Qwen/Qwen2.5-7B-Instruct",
  "eval_checks": [
    { "kind": "valid_json", "target": 95 },
    { "kind": "within", "tolerance": 10, "tolerance_unit": "percent", "target": 70 },
    { "kind": "latency", "max_ms": 2000 }
  ]
}

When the job ends, progress.eval.checks on the job gives each check’s share of passing answers for the base model and the fine-tune, its target, and whether the target was met, with targets_met and targets_total. See Checks.

Fine-tuning, outputs

Tool	What it does
`get_job_outputs`	List a completed job’s output artifacts.
`download_job_outputs`	Download outputs (convenience wrapper).
`plan_job_output_download`	Plan a (possibly large) output download.
`start_job_output_download`	Start a planned download.
`get_job_output_download_status`	Check download progress.
`get_job_output_download_urls`	Get signed URLs for a job’s outputs.

Datasets

Tool	What it does
`list_datasets`	List your datasets.
`get_dataset`	Get a dataset’s info.
`get_dataset_upload_url`	Get a presigned URL to upload a dataset.
`download_dataset`	Get a signed URL to download a dataset.
`delete_dataset`	⚠ mutating Delete a dataset.
`suggest_eval_checks`	Suggest the checks to test a fine-tune on a dataset with, each with a starting target. See Eval checks.

GPU availability

Tool	What it does
`get_gpu_availability`	Check available GPU types and capacity.
`check_gpu_for_deployment`	Check whether a specific GPU is available for a deployment.

Logs

All log tools return GPU-workload and deployment output, not Valkyrie’s own internal application logs.

Tool	What it does
`get_job_logs`	A fine-tuning job’s logs.
`get_deployment_logs`	A deployment’s logs.
`get_vllm_service_logs`	The serving engine’s logs.
`get_persisted_logs`	DB-persisted logs for a job or deployment.
`collect_logs_now`	Force an immediate log collection.

Paging through persisted logs

get_persisted_logs returns stored logs one bounded page at a time, so large log histories don’t time out your client:

Each page holds up to 10 log entries, newest first. Valkyrie truncates long entry text, so a single page stays small.
The response includes next_before_id. Pass it back as before_id to fetch the next, older page. Repeat until you reach the entries you need.
To jump straight to an earlier incident, pass collected_before with a UTC ISO-8601 timestamp that includes a timezone, such as 2026-09-20T14:00:00Z. Valkyrie returns only entries collected before that time. A timestamp without a timezone returns an error.
tail_lines limits the lines in combined_logs for the page, up to 500.

For example, to page backwards from an incident on a deployment:

{
  "deployment_id": 34,
  "collected_before": "2026-09-20T14:00:00Z"
}

Then call again with "before_id": <next_before_id> from the previous response. get_deployment_logs returns stored logs directly for a deployment whose instance is stopped or terminated. It doesn’t try a live fetch from the instance. These responses have "source": "persisted" and contain the most recent page of stored entries. Use get_persisted_logs with deployment_id to page further back.

Aliases

An alias is a stable URL, /{account_slug}/{alias}/v1, that points at a deployment or an inference pool. See Aliases.

Tool	What it does
`list_aliases`	List your aliases. Each has `target_type` (`deployment` or `inference_pool`), `instance_id` or `inference_pool_slug`, and `public_url_path`.
`create_alias`	⚠ mutating Create an alias for a deployment or a pool. Give exactly one of `instance_id` and `inference_pool_slug`. `alias` is 2 to 64 characters (`a-z`, `0-9`, `-`) and is generated if omitted. The pool must be yours and in the same workspace.
`update_alias`	⚠ mutating Re-point an alias at another deployment or pool. Give exactly one of `instance_id` and `inference_pool_slug`. The URL stays the same.
`delete_alias`	⚠ mutating Delete an alias. Its URL stops answering. The deployment or pool isn’t touched.

A pool alias answers only account-wide API keys. See Point an alias at an inference pool.

Inference pools

A pool puts several deployments of the same model behind one endpoint (/inference-pools/{pool}/v1, or an alias that points at the pool). Valkyrie routes each request to a healthy member with a free request slot and queues it when every slot is busy. A pool is managed when it has a member template and a desired_size. Valkyrie then deploys members from the template (billed like any deployment), replaces members it loses, and drains and removes extra ones when you lower the size. A pool without a template never provisions or tears down deployments: you add and remove existing deployments yourself.

Managed pools are switched on per environment. Where they aren’t on yet, a managed pool keeps its template and sizes but deploys nothing, and behaves like a pool without a template. Contact support if a managed pool’s members don’t appear.

Tool	What it does
`list_inference_pools`	List pools you’re authorized for.
`get_inference_pool`	One pool’s configuration, size, and each member’s state (provisioning, active, draining, failed).
`pool_status`	Live state of a pool’s endpoint: free and busy request slots, the wait queue, each member’s health, and the pool’s active worker runs.
`create_inference_pool`	⚠ mutating Create a disabled pool from existing deployments, a member template, or both. With a template and `desired_size`, the pool deploys members, which spends from your wallet.
`update_inference_pool`	⚠ mutating Change the state, session lifetime, or the scaling of a managed pool (`template`, `min_size`, `desired_size`, `max_size`). Lowering `desired_size` drains and removes extra members. `managed=false` stops managing the size and leaves the members as they are.
`add_inference_pool_member`	⚠ mutating Add a deployment to a pool. It must serve the pool’s model with the same runtime profile and pass a health check.
`update_inference_pool_member`	⚠ mutating Set a member’s request slots (`slot_capacity_override`), or pass null to use the slots from its runtime configuration.
`replace_inference_pool_member`	⚠ mutating Swap the member at a position for another deployment. `disposition` is `require_empty` (refuse while it serves a request) or `revoke` (running requests finish on the old member).
`remove_inference_pool_member`	⚠ mutating Take a member out of the pool. The deployment keeps running. An active pool must keep at least one active member.
`delete_inference_pool`	⚠ mutating Delete a disabled pool.

Each member’s request slots come from its runtime configuration unless you set slot_capacity_override.

Worker tasks on pools

Worker tools queue an agent task on a pool. A worker runner on your side picks up the run and runs the agent against the pool’s endpoint. Valkyrie routes its model requests, holds the slots and the queue, and keeps the run record.

Tool	What it does
`worker_start`	⚠ mutating Queue a task on a pool and return its `run_id`. Optional `label`, and `cwd`, `tools` and `thinking` passed to the runner’s agent.
`worker_wait`	Wait until every named run has ended, or up to `timeout_seconds` (at most 600). Returns each run’s status, last turn, and result.
`worker_status`	One run: status, turns, tool calls, the member serving it, the last completed turn, the result, and its events after `after_seq`.
`worker_list`	Your recent runs, newest first. Filter by pool, or by status (`active` means queued and running).
`worker_cancel`	⚠ mutating Cancel a run. A queued run ends at once; a running one stops at the runner’s next report.

MCP

​Server

​Deployments, inspect

​Deployments, create & lifecycle

​Deployments, schedules & auto-recovery

​Deploy options

​Fine-tuning, jobs

​Eval checks

​Fine-tuning, outputs

​Datasets

​GPU availability

​Logs

​Paging through persisted logs

​Aliases

​Inference pools

​Worker tasks on pools

Server

Deployments, inspect

Deployments, create & lifecycle

Deployments, schedules & auto-recovery

Deploy options

Fine-tuning, jobs

Eval checks

Fine-tuning, outputs

Datasets

GPU availability

Logs

Paging through persisted logs

Aliases

Inference pools

Worker tasks on pools