AI agents (MCP)

Meshive runs a hosted MCP (Model Context Protocol) server. Connect it to an AI coding agent and you can ask things like “what GPUs can I rent right now?”, “start a pod with an RTX 3060 for my training run”, or “show me the last lines of that pod’s logs” — the agent calls the same API the SDK and CLI use.

https://mcp.meshive.ai/mcp

The server is stateless and stores nothing about you. Your API key travels in the request header your client sends and is forwarded to the Meshive API as-is. It is open source at github.com/meshive/meshive-mcp.

Connect your agent

You need a Meshive API key from the console (workspace Settings → API keys). A Read only key lets the agent look at everything; a Read & write key also lets it create, change and delete resources — see Authentication for how the two differ and why write keys expire.

Every client sends the key as Authorization: Bearer meshive_….

Claude Code

claude mcp add --scope user --transport http meshive https://mcp.meshive.ai/mcp --header "Authorization: Bearer meshive_..."

--scope user makes it available in every folder — without it, only in the folder where you ran the command. Check with claude mcp list. To switch to a new key, run claude mcp remove meshive first; add refuses a name that already exists.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.meshive]
url = "https://mcp.meshive.ai/mcp"
http_headers = { "Authorization" = "Bearer meshive_..." }

To keep the key out of the file, use bearer_token_env_var = "MESHIVE_API_KEY" instead of http_headers and set that variable wherever Codex starts. A variable exported in one terminal isn’t seen by other terminals, the IDE extension or the desktop app.

Cursor

In ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project). If the file already has mcpServers, add just the meshive entry:

{
  "mcpServers": {
    "meshive": {
      "url": "https://mcp.meshive.ai/mcp",
      "headers": { "Authorization": "Bearer meshive_..." }
    }
  }
}

Gemini CLI

gemini mcp add --scope user --transport http --header "Authorization: Bearer meshive_..." meshive https://mcp.meshive.ai/mcp

This adds the server to ~/.gemini/settings.json and leaves your other settings alone. Without --scope user it goes to the current project’s .gemini/settings.json. Run it again with a new key to replace the old one.

Other clients

Any client that supports the Streamable HTTP transport with custom headers works the same way: URL https://mcp.meshive.ai/mcp, header Authorization: Bearer meshive_....

Clients that only support stdio can bridge with the generic mcp-remote shim:

{
  "mcpServers": {
    "meshive": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.meshive.ai/mcp",
               "--header", "Authorization: Bearer ${MESHIVE_API_KEY}"]
    }
  }
}

To check the connection, ask the agent “Which Meshive workspaces do I have?” — it should call the workspaces tool. If it reports no_api_key or invalid_api_key, the header is missing or the key was rejected.

What the agent can do

Tool	What it does
account	Who the key belongs to, credit balance
workspaces	List workspaces, or one workspace with its cost summary and members
pods	Pods in a workspace (or all workspaces), or one pod with its URLs, logins and live metrics
transactions	Pod operations still in flight — why a pod is still creating, and why an input asset download failed — or, with transaction_id, one operation and how it ended, even after it has left the list
models, detect_model	Models registered for serving, and whether a Hugging Face repo can be served
watched_folders	A pod’s watched folders — folders whose new files are uploaded as assets
source_credentials	IDs and labels of the workspace’s saved Hugging Face tokens and CivitAI keys — never the secrets
download_links	Temporary download links for an asset’s files or a task’s outputs — links only, never file contents
storages	Storage volumes of a workspace
gpus	GPU types available to rent with hourly prices — works without a key (prices only)
cpus	CPU lines available for CPU pods, with hourly prices per vCPU and per GiB of RAM — the cpu_line to pass to estimate_pod and create_pod
templates	Pod templates you can launch from
model_sets	The model sets a template offers — ready-made bundles of model files, with size, minimum GPU memory and licenses — for estimate_pod and create_pod’s model_set
servings, tasks	Serverless deployments and one-off jobs
assets	Asset Hub datasets, models, adapters, outputs
machines	Machines you host, with earnings and live metrics
billing_history	Credit top-ups and refunds, or host earnings by day
logs	Last lines of a pod’s or a task’s logs
estimate_pod, estimate_task	Price before anything is spent
operation_status	Read the acceptance record for a write using its operation_id and original method/path
create_workspace	Create a workspace — it costs nothing by itself (write key; MCP server 1.6+)
update_workspace	Rename a workspace — its ID stays the same and every member sees the new name (write key; MCP server 1.6+)
delete_workspace	Delete an empty workspace — it can’t be undone, and a workspace that still holds anything is refused (write key; MCP server 1.6+)
create_pod, stop_pod, start_pod, restart_pod, delete_pod	Pod lifecycle (write key)
update_pod	Change a pod like the console’s Edit — name, template, hardware, variables, ports, command, storage (write key)
create_storage, delete_storage	Network storage volumes (write key); local storage is created together with a pod
update_storage	Rename a volume, grow it or set its usage warning (write key)
ssh_access, connect_storage	One-time SSH command and password for a pod, or for a storage volume’s files like the console’s Connect (write key)
set_watched_folders	Change a running pod’s watched folders without a restart (write key; confirm when adding or turning one on)
import_asset	Link a Hugging Face repo, CivitAI model or file URL as an asset (write key; no copy, no storage charge)
register_model, delete_model	Register a Hugging Face model for serving, or remove a registration (write key)
deploy_serving, scale_serving, pause_serving, delete_serving	Servings (write key)
submit_task, stop_task	Tasks (write key)

Workspaces and pods can be named by their display name; the server resolves it to the ID, except confirm: true on update_workspace and delete_workspace, which take the ID only. Lists are paged, so a long list comes back in chunks the agent walks through. Errors come back with a machine-readable code and a next_step the agent follows — for example, after a rate limit it waits instead of hammering the API.

Spending and deleting start with a preview

Tools that spend or delete return a preview unless the agent sets confirm, and the agent is told to ask you before going further. The tools that create (create_workspace, create_pod, create_storage, deploy_serving, submit_task), change (update_workspace, update_pod, update_storage, connect_storage), delete (delete_pod, delete_storage, delete_workspace, delete_serving, delete_model) or raise billing (start_pod, pause_serving with paused: false, which resumes billing, scale_serving when the change can raise the hourly cost — a larger replica range, autoscale on, a higher price cap) take a confirm flag that defaults to off. Without it they only return an estimate — the hourly price and the hardware it resolved to, and for an edit the changes and the price before and after — or a summary of what would be deleted, started or connected, and change nothing. The server tells the agent to show that to you and to call again with confirm only after you have said yes in the conversation. register_model and import_asset have no confirm step because they cost nothing — an imported asset is linked, not copied; the model downloads, and billing starts, only when deploy_serving is confirmed. create_workspace costs nothing by itself either, but it has the step too: without confirm it only shows the name (or says one will be generated) and creates nothing. update_workspace costs nothing as well and has the step because every member sees the new name: without confirm it only shows the old and the new name.

A typical exchange:

1. “Create an RTX 3060 pod from the VSCode template in my workspace.” — the agent looks up the workspace, template and GPU availability, calls create_pod without confirmation, and shows you: $0.068/hour, 1× RTX 3060 12 GB, 4 vCPU / 15 GiB RAM, 25 GiB disk.
2. “Yes, go ahead.” — the agent calls create_pod with confirm: true and the preview’s operation_id, then polls pods until the pod is running and reports the billed rate. If the pod doesn’t appear, it calls transactions with the transaction_id that create_pod returned and tells you why the creation failed.
3. “Delete it.” — the agent shows the pod it is about to delete and waits for your yes again.

Every accepted change is asynchronous. The agent polls the matching list tool for the new state rather than assuming it.

Caution

confirm is an argument the agent sets. The server can’t tell whether a person said yes, and nothing forces a preview first, so an agent with a write key that ignores these instructions can spend or delete directly. A key reaches every workspace you can access and has no spending limit of its own. Only a read-only key actually prevents writes. Read the estimate the agent shows you before saying yes, give write keys only to agents you trust, and keep them short-lived.

Write IDs and recovery

Every write requires a stable operation_id (8–128 characters: letters, digits, ., _, :, -). A write preview returns one; the agent must reuse it for confirmation and every retry. For tools without a preview, such as stop_pod, generate a UUID before the first call. A confirmed write without a supplied ID is refused with operation_id_required before mutation.

Results and errors retain the ID. When available, operation_lookup supplies the original method and path. To inspect an uncertain task submission without resubmitting it, call operation_status with:

{
  "operation_id": "the-saved-operation-id",
  "method": "POST",
  "path": "/tasks"
}

Use the SDK-relative path without /v1/sdk or a query string. done means the acceptance response was recorded, so the agent must still check the resource. pending and unknown require reconciliation; the ID does not expire automatically. not_found alone is not permission to replace the ID and resubmit. See the SDK recovery states.

Creating a workspace

With a write key the agent can create a workspace (MCP server 1.6+). When workspaces comes back empty it offers to create one, and you can ask for one directly: “Create a workspace called research.” create_workspace follows the console’s rules. The name is optional, at most 63 characters, without control characters, and different from every workspace name you already use — an exact match, so Research and research count as different names. Leave it out and a name starting with my-workspace- is generated. A name that is taken comes back as name_taken and nothing is created.

An empty workspace costs nothing; pods, storage and tasks in it are billed as usual. Creation is asynchronous: the response arrives before the workspace can be used, so the agent is told to call workspaces until its status is running before it creates anything in it. A pod or task requested too early is refused (workspace_not_ready), and storage or a serving may be accepted and fail later, so the wait matters. A just-created workspace can be missing from the list for a moment. error, or a terminated that doesn’t change, means setup failed. If it is still creating after a few minutes, the agent is told to say it is taking longer than usual and not to create another.

A new workspace does not limit your API key. A key works in every workspace you can access, so the key you already use works in the new one, and every workspace you are the billing owner of draws on the same credit.

Renaming a workspace

update_workspace changes a workspace’s name and nothing else (MCP server 1.6+). The workspace ID stays the same, every member sees the new name, and it needs the admin or billing role in that workspace — a viewer is refused. The name follows the rules of create_workspace except that it can’t be left out: at most 63 characters, no control characters, and different from the names of your other workspaces (name_taken otherwise).

Without confirm it shows the current and the new name and changes nothing; after your yes, the agent calls again with confirm: true. The rename is applied at once, but the workspace list can take a moment to show the new name, so the agent is told to keep using the ID.

Both update_workspace and delete_workspace require workspace and never pick one for the agent, even when you have only one workspace. On the preview it can be the ID or the name; with confirm: true it must be the ID the preview returned, because a name stops matching once the workspace is renamed or deleted, and a retry would then fail.

Deleting a workspace

delete_workspace deletes a workspace that is empty, and only that (MCP server 1.6+). It needs a write key and the admin or billing role in that workspace, and it can’t be undone.

Without confirm it checks the workspace and deletes nothing. If the workspace is empty, it returns a preview that names the workspace and says the deletion can’t be undone, and the agent asks you. If anything is left, it returns workspace_not_empty with blockers, a count for each kind of thing still in the workspace. The agent is told to tell you what is left and to clear nothing you didn’t ask it to: pods, storage volumes, servings and custom models can be deleted, and running tasks stopped, with their tools if you ask; assets, finished tasks, credentials, webhooks, custom templates, inference keys, members and invitations are managed in the console. Two things clear by themselves: operations still finishing (usually within minutes, at most about 30 minutes), so the agent checks again shortly, and task outputs still being saved (about 30 minutes after a task ends, or when its upload finishes); if task_outputs is still listed after about 30 minutes, it stops checking and tells you to look at the task in the console or contact support. Payouts waiting to be credited clear once the earnings are paid out, usually within a day; earnings on hold, or a failed payout, can take longer, so it tells you to contact support, and a delete in the console before that loses them. It is told never to look for a way around the check.

A workspace counts as empty when none of these is left (blockers uses the names in parentheses):

• pods, stopped ones and system pods included (pods), storage volumes (storages) and servings, paused ones included (servings)
• tasks that are running or queued, and finished tasks that are still in the Tasks list (tasks), and tasks whose outputs are still being saved (task_outputs)
• assets, frozen ones included (assets), custom templates (templates) and custom registered models (models)
• saved credentials — Hugging Face tokens, CivitAI keys, object-storage credentials and registry logins (credentials), webhooks (webhooks) and active inference API keys (inference_keys)
• other members (members) and invitations sent in the last day that haven’t been accepted (invitations)
• earnings from shared serving capacity that haven’t been credited yet (pending_payouts)
• operations that are still running, including the workspace’s own setup (operations_in_progress)

Your own meshive_… API keys, billing history, short-lived inference results, files in your own bucket, links added when you attach a model set (the ”+ N assets from model sets” entry on the Assets page; Meshive stores none of those files) and anything you have already deleted don’t count, except a removed task whose outputs are still being saved (task_outputs). The SDK reference says what each kind means and how to clear it.

The check is enforced by the server, not only by the agent’s instructions: a key can’t delete a workspace that still holds things even if the agent skips the preview. It does not make a write key harmless — a key can still delete pods, storage volumes and servings one at a time — and no tool can delete a workspace that still holds things. A person can still delete it in the console, which removes what’s in it for good; the SDK reference says how the console treats it.

After the confirmed call, the deletion is accepted and runs in the background: the workspace leaves the workspaces list within a moment, and its name stays taken for a while. Other refusals come back as workspace_not_deletable with the reason, such as a protected workspace. The key’s owner gets an email naming the key. See the SDK reference for what a delete removes and how the name is freed.

Pod settings follow the console

estimate_pod and create_pod take the settings of the console’s create flow, and the server checks them the same way:

• CPU pods. Leave out gpu_model. cpu_line picks the CPU line — a cpu_line value from the cpus tool; without it, the cheapest line that fits is used. vCPU and RAM default to 8 cores and 32 GiB, as in the console (or the nearest sizes the line offers).
• Sizes. vcpu and ram_gb must be sizes the console offers. A refused size comes back as vcpu_not_offered or ram_not_offered with the allowed values.
• Storage. volumes attaches existing network storage from the storages tool. local_volumes creates new local storage on the pod’s machine together with the pod — for example [{"name": "scratch", "mount_path": "/scratch", "size_gb": 50}], optionally with "encrypted": true — at least 10 GiB each, and not for spot pods. It is billed by size until it is deleted, also while the pod is stopped, and the estimate the agent shows you includes it. create_storage creates network storage only, of at least 10 GiB; with usage_warning: true you get an email when the volume fills past usage_warning_threshold (0–1, default 0.9), like the console’s usage warning.
• Ports. ports opens new ports; a port or port name the template already opens can’t be added again. template_ports changes the ports the template opens, like the console’s deploy screen — for example [{"port": 8188, "name": "ui", "new_port": 8189, "external": false}], where port is the template’s port as it is now and name (rename), new_port (renumber) and external (true exposed over HTTPS, false internal only) are optional. Template ports can’t be removed.
• Variables and command. Environment variables the template requires need a value, and the start command is limited to 4,096 characters.
• Assets and watched folders. input_assets places Asset Hub assets in the pod; paths picks some of an asset’s files (a path that matches no file is refused), and "strip_prefix": "" keeps their folder structure, like the console’s Keep structure. watched_folders adds folders whose new files are uploaded as assets, and watched_template_folders turns off the template’s own watched folders, changes their patterns or moves an output folder from the start — for example {"/outputs": {"enabled": false}} or {"/workspace/output": {"path": "/workspace/results"}}. Templates without an output folder take watched_folders too when the pod has storage for them, and update_pod with enable_folder_saving adds the uploader to an older pod that has none.

Each refusal comes back with its own code — port_in_use, port_name_in_use, port_not_in_template, required_env_missing, command_too_long, … — and a next_step; for a missing variable the agent is told to ask you for the value rather than invent one.

region (pods and storage) and disk_type (storage) are still accepted but ignored.

Price caps and moving a pod

Pod/task max_price_per_hour caps the final compute rate including CPU/RAM, with another check before placement. Before a pod is created, the cap is also checked against its estimate, which includes any new local_volumes. An accepted pod creation can fail asynchronously if its final rate is over the cap. Existing volumes you attach, automatic volumes and Asset Hub retention are billed separately. Task input fetching can add compute time; an estimate is not a total-bill ceiling.

start_pod takes an optional placement. Leave it out and the server picks what the console’s Start button would: a pod already waiting for any machine keeps waiting for one (wait_any_node); a pod that can no longer run on its original machine starts on another one (any_node, or wait_any_node if none has room yet); any other pod starts on its original machine (same_node, or wait_same_node if it has no room yet). The result’s placement says which one was used. Or choose one: same_node starts the pod on its original machine and any_node on any machine with room, while wait_same_node and wait_any_node do the same but, when no machine has room yet, leave the pod waiting and start it as soon as one does. When you choose same_node or any_node and no machine can take the pod right now, the error (no_available_node) tells the agent to ask you whether to wait.

any_node and wait_any_node can move the pod to another machine. For both, the preview includes has_unpreserved_workspace in the pod details, storage charges and a loss warning. The agent is told to set confirm: true only after you agree to resume billing. When unpreserved files might be lost, the tool also needs allow_data_loss: true, which the agent is told to set only after your separate consent to that pod’s move. Without it, the tool returns a preview even if confirm is true. Local volumes remain on the original machine.

Without a placement, whether the pod moves is known only from the server’s answer, so allow_data_loss is sent only together with an explicit placement. If the pick would move a pod with unpreserved workspace files, nothing starts: the tool returns data_loss_consent_required naming the placement, and the agent is told to show you the loss warning and, only after you agree, call again with that placement and allow_data_loss: true.

Editing pods and storage

update_pod takes only what changes, like the console’s Edit: name, template_id, rental_type, gpu_model / gpu_vram_gb / gpu_count (GPU pods), cpu_line (CPU pods), vcpu and ram_gb, env and remove_env, ports, template_ports and remove_ports, command ("" goes back to the template’s), and storage — volumes attaches network storage or local storage on the pod’s current machine, local_volumes creates new local storage there, and detach_storages detaches volumes (their data stays). Changing the GPU resets vCPU and RAM per GPU to the new GPU’s recommended sizes, changing only gpu_count keeps the per-GPU ratio, and changing the CPU line resets cores and RAM to the console’s default. The pod type (GPU or CPU), premiums and image can’t change, and the template’s own variables and ports can’t be removed.

The preview lists the changes, the hourly price before and after, and whether the pod restarts: a running pod restarts with the new settings, a stopped pod uses them at its next start, and a rename alone doesn’t restart it. Input assets and watched folders are kept.

Some edits stop and ask first; nothing changes until you agree:

• node_migration_required — the pod’s machine can’t fit the change. The agent asks whether the pod may move, and only then calls again with allow_node_migration: true. A move permanently deletes unpreserved workspace files, so for a pod with any, the tool also needs allow_data_loss: true, which the agent is told to set only after your separate consent, as for start_pod.
• cannot_change_resources — attached local storage keeps the pod on its machine, which can’t fit the change. The agent asks whether to detach that storage or keep the current resources.
• harvest_roots_orphaned — the edit removes the storage that watched folders are on. The agent shows you the folders and passes them as drop_watched_folders only after you agree.

update_storage renames a volume, grows it (it can’t shrink) or sets its usage warning; the preview shows the new size and the hourly price before and after.

A typical exchange: “Give my-pod two GPUs instead of one. What will it cost?” — the agent calls update_pod with gpu_count: 2 and no confirm, and shows you the change, the new hourly price and that the running pod will restart. After your yes it calls again with confirm: true, then polls pods until the pod is running again.

Starting a pod with a model set

model_sets lists the model sets a template recommends, like the console’s model set tiles. Pass one set’s slug as model_set to estimate_pod and create_pod; a pod takes one set, and the estimate shows its file count, size and minimum GPU memory. A template that adds its own set automatically, or has no model folders, takes none.

A set marked hf_token_required is gated on Hugging Face, such as FLUX 3 Image Klein: you accept its license on the page in gated_sources with your Hugging Face account, and the agent creates the pod from the set’s Quick Deploy template with hf_token_id — a token of that account from source_credentials (MCP server 1.3+). If the token’s account hasn’t accepted the license, the agent is told so and asks you to accept it first. See Gated model sets.

The set’s files are added before the pod is created, so a confirmed create_pod with model_set can take several minutes to answer. If the call times out, the agent is told not to create the pod again but to check operation_status and pods first. If a file can’t be added, no pod is created and nothing is billed (model_set_unavailable, with the files that failed); files already added are reused next time.

Amounts match the console

Money fields come with a ready-made display string — for example, a pod’s price_per_hour_display: "$0.068" next to price_per_hour: "0.06770833" — formatted the way the console formats them: hourly rates to three decimals, everything else to two. The agent is told to show that string and to use the raw number only for its own arithmetic, so the price it quotes you is the price you see in the console.

Pod logins stay hidden

A pod’s connect_credentials are the logins the console shows on Connect, such as the ACCESS_PASSWORD a ComfyUI pod generates. Secret values come back as null in every response, including the previews of start_pod, stop_pod and delete_pod. The agent gets a value only by asking pods for one pod with show_secrets: true, which it is told to do only when you ask for the login, and that response reminds it to give the value to you and nowhere else. With a read-only API key the value comes back as ***, and the response says a key with write scope is needed. ssh_access works the same way for a one-time SSH password: the agent is told to call it only when you want to connect, it leaves out the browser-terminal link (the password is in it), and the password expires in a few minutes.

connect_storage gives the same kind of login to a storage volume’s files, like the console’s Connect. Its preview says what will happen — for encrypted storage, that the volume is unlocked and locks again by itself after a while — and only the confirmed call returns a password. That call waits up to wait seconds (0–90, default 60) for the volume to be ready; if it isn’t yet, the agent is told to call again shortly. Neither ssh_access nor connect_storage keeps a replayable copy of the response, so the password can’t be fetched again from an operation record.

Logs are treated as data

logs returns whatever your container printed — and transactions returns the end of a failed asset download’s log as init_logs — so anything running inside it — including third-party code you did not write — can put text in front of the agent. The tool’s description, its response and the server instructions all tell the agent that log lines are untrusted data: never to follow instructions found in them, and never to call a write tool because a log line asked. The confirm step above is the second line: the agent is also told to get your explicit yes in the conversation before a write tool spends or deletes. Both are instructions to the agent, so use a read-only key when the agent will read logs you don’t trust.

Limits

• The server exposes what the SDK exposes. Managing API keys and Hugging Face tokens, host machine settings, and deleting a workspace that still holds things stay in the console.
• Log tools return a snapshot of the last lines (up to 1000, 64 KiB), not a live stream.
• Task scripts should print(..., flush=True); buffered output that is never flushed does not reach the logs.
• submit_task and estimate_task take output_include — glob patterns such as ["*.safetensors"] — to upload only the matching files in /outputs, like the console’s Files to save.
• The final tool response, including text and structured content, is limited to 1 MiB. On response_too_large, request fewer items or log lines. If it followed a write, check the operation/resource before retrying: a response error does not undo an accepted write.
• For external task logs, pass the previous next_cursor as cursor; pod logs remain snapshots. Check the response note for freshness warnings.