MCP server
The Viam MCP server exposes your Viam organizations, locations, machines, fragments, datasets, and training jobs to an MCP client such as Claude, Claude Code, ChatGPT, or Codex. Once connected, the client can look up fleet and machine information, read and edit machine and fragment configuration, manage datasets and sequences, run custom training jobs, and call APIs on live machines on your behalf.
Connect
Add the Viam MCP server to your MCP client as a remote server at:
https://app.viam.com/mcp
The server uses OAuth: your MCP client redirects you to sign in to Viam and authorize access, then uses the resulting token for subsequent tool calls. You must accept Viam’s terms of service before any tool call succeeds; if you haven’t, a tool call returns an error with a link to do so.
Every tool call is scoped to the organizations, locations, and machines your Viam account can already access. The MCP server does not grant any access beyond your existing permissions.
Tools that connect to a live machine, in either Live machine category, use that machine’s default API key, and create the key if the machine has none.
Tool categories
Tools fall into seven groups, reflected in the Category column below:
- Read-only and Read-only (external) tools only read and change nothing, so most MCP clients don’t prompt for confirmation before running them. Read-only tools query Viam’s own data (your fleet, a machine’s saved configuration). Read-only (external) tools, such as
read_viam_docs, search an index outside Viam: a third-party search service that draws mainly on docs.viam.com and returns each passage with the URL it came from. - Read (billable) tools,
read_machine_logsandread_training_job_logs, read data and change no configuration, but they aren’t marked read-only to MCP clients: returning logs records billable data egress for the organization that owns the machine or training job. Many clients ask for confirmation before running them.read_training_job_logsis also marked destructive, so clients that run non-destructive tools without asking still ask before running it. - Live machine (read-only) tools, such as
read_machine_apiandget_world_state, connect to an online machine and read its current state. They don’t move hardware or change configuration, but they aren’t marked read-only to MCP clients: connecting uses the machine’s default API key and creates that key if the machine doesn’t have one yet. Many clients ask for confirmation before running them. They need the machine to be reachable and can take longer to answer than the other read tools. - Write tools create or add configuration or data, such as a machine, a config item, or a dataset. Most clients ask for confirmation before running one.
- Write (destructive) and Live machine (destructive) tools change or delete existing configuration or data, start or cancel billable work such as a training job, or act directly on a live machine (for example, moving hardware with
call_machine_apiorrun_docommand). These save or act immediately, with no draft and no undo, so review what a tool is about to do before approving it.
The fragment tools (create_fragment, add_fragment_config_item, update_fragment_config_item, and delete_fragment_config_item) change fragments. If a fragment is public or unlisted, users outside your organization can see and use its configuration, including your changes.
The favorite machine tools (list_favorite_machines, add_favorite_machine, and remove_favorite_machine) read and change your own machine favorites, which no one else in your organization sees. remove_favorite_machine is marked destructive because it deletes a favorite, but it never changes the machine itself.
set_machine_config and set_machine_config_properties are experimental and may change or be removed. set_machine_config replaces a machine part’s entire saved configuration, and refuses the change if the configuration has changed since read_machine_config returned it. set_machine_config_properties sets individual properties by dotted path, such as components.my-camera.attributes.fps.
The dataset and sequence tools (list_datasets, create_dataset, delete_dataset, list_sequences, read_sequence, update_sequence, delete_sequences, add_sequences_to_dataset, and remove_sequences_from_dataset) manage datasets and their sequences. Deleting a dataset or removing sequences from it keeps the captured images, readings, and sequences; only their membership in the dataset is removed. delete_sequences deletes the sequences themselves but keeps the data captured during them.
The training tools (list_training_scripts, list_training_containers, submit_training_job, list_training_jobs, read_training_job, read_training_job_logs, and cancel_training_job) run custom training jobs. Each submit_training_job call starts a new job, billed to the dataset’s organization for its GPU time, so it is marked destructive and is not safe to repeat: a call that fails or times out may still have started a job, so check list_training_jobs before submitting again. cancel_training_job cancels a pending or in-progress job; GPU time used before the cancellation is billed.
The machine and fragment config item tools also add, re-pin, and remove entries in a configuration’s packages section, such as an ML model at a pinned version. They check that the package exists and that the version is published or latest, and they refuse to remove or rename a package that a resource or module still uses.
The simulation tools (read_simulation, start_simulation, and stop_simulation) manage a cloud simulation of a machine part. Starting a simulation is billed by the minute to the machine’s organization, so stop_simulation ends the charges.
Tools
To learn what a particular tool can do, ask an AI assistant that’s connected to the Viam MCP server. See Connect.
| Tool | Category |
|---|---|
get_registry_item_information | Read-only |
list_datasets | Read-only |
list_favorite_machines | Read-only |
list_machines | Read-only |
list_organization_locations | Read-only |
list_organizations | Read-only |
list_sequences | Read-only |
list_training_containers | Read-only |
list_training_jobs | Read-only |
list_training_scripts | Read-only |
read_fragment_config | Read-only |
read_inline_module_code | Read-only |
read_machine_config | Read-only |
read_machine_metadata | Read-only |
read_part_status | Read-only |
read_sequence | Read-only |
read_simulation | Read-only |
read_training_job | Read-only |
retrieve_skill | Read-only |
search_configuration_blocks | Read-only |
read_viam_docs | Read-only (external) |
read_machine_logs | Read (billable) |
read_training_job_logs | Read (billable) |
get_world_state | Live machine (read-only) |
read_machine_api | Live machine (read-only) |
add_favorite_machine | Write |
add_fragment_config_item | Write |
add_machine_config_item | Write |
add_sequences_to_dataset | Write |
create_dataset | Write |
create_fragment | Write |
create_machine | Write |
start_simulation | Write |
cancel_training_job | Write (destructive) |
delete_dataset | Write (destructive) |
delete_fragment_config_item | Write (destructive) |
delete_machine_config_item | Write (destructive) |
delete_sequences | Write (destructive) |
remove_favorite_machine | Write (destructive) |
remove_sequences_from_dataset | Write (destructive) |
set_machine_config | Write (destructive) |
set_machine_config_properties | Write (destructive) |
stop_simulation | Write (destructive) |
submit_training_job | Write (destructive) |
update_fragment_config_item | Write (destructive) |
update_machine_config_item | Write (destructive) |
update_sequence | Write (destructive) |
call_machine_api | Live machine (destructive) |
run_docommand | Live machine (destructive) |
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!