API & Tool Reference.md

API & Tool Reference

This page is the reference index for the ProxmoxMCP-Plus tool surface, the native MCP Streamable HTTP endpoint, and the OpenAPI wrapper that exposes tools as REST-style HTTP routes.

Use this page when you need exact tool names, input shapes, prerequisites, or common failure patterns. Use the Operator Guide for deployment and runtime setup, and the Security Guide for policy and access controls.

How To Read This Page

• Read-only tools inspect Proxmox state and should be your first call when validating reachability or inventory.
• Mutating tools create, start, stop, change, restore, or delete infrastructure.
• Tool availability depends on runtime configuration. In particular, some command-execution tools are only registered when ssh config is present.
• MCP Streamable HTTP mode exposes the native MCP endpoint at /mcp.
• OpenAPI mode is a bridge over the same MCP tool surface. The generated schema at /openapi.json is the source of truth for the exact request and response shape exposed by the running server.

Native MCP Streamable HTTP Endpoint

When mcp.transport is STREAMABLE_HTTP or STREAMABLE, the server exposes the MCP endpoint at:

Path	Purpose	Notes
/mcp	MCP Streamable HTTP endpoint	use this for remote MCP clients that support Streamable HTTP

The Docker Compose mcp-http profile exposes this endpoint on port 8000. When MCP_API_KEY is set, callers must send Authorization: Bearer <MCP_API_KEY>. Missing or incorrect credentials return 401 with WWW-Authenticate: Bearer.

OpenAPI Service Endpoints

When the OpenAPI wrapper is enabled, the primary endpoints are:

Path	Purpose	Notes
/	service metadata	basic wrapper metadata
/docs	Swagger UI	interactive API docs for the currently running tool set
/openapi.json	generated OpenAPI schema	reflects conditional tool registration such as SSH-backed tools
/livez	liveness check	unauthenticated, minimal process liveness
/readyz	readiness check	requires OpenAPI auth and reports MCP backend connectivity
/health	readiness alias	requires OpenAPI auth and matches /readyz
/metrics	Prometheus metrics	includes per-route labels for route, method, and status
/jobs	persistent job list	requires a local JobStore in the OpenAPI process

Global Behavior And Constraints

Authentication and Authorization

• Proxmox API access requires a valid proxmox and auth configuration.
• Native MCP Streamable HTTP access optionally requires Authorization: Bearer <MCP_API_KEY> when MCP_API_KEY is configured.
• OpenAPI access requires Authorization: Bearer <PROXMOX_API_KEY> by default. Startup without an API key requires the explicit local-development override PROXMOX_ALLOW_NO_AUTH=true.
• SSH-backed container command workflows require a valid ssh configuration.
• Command-execution tools are subject to command-policy checks. Depending on policy, a request can be allowed, denied, or require an approval_token.
• Detailed policy behavior lives in the Security Guide.

Output Conventions

• Some tools return human-readable text by default.
• Several container tools support format_style with pretty or json.
• In HTTP mode, exact request and response payloads should be verified against /openapi.json for the running server version.
• Long-running mutating tools can return both a raw Proxmox task_id and a stable job_id.

Job Tracking Conventions

• job_id is the MCP and OpenAPI stable identifier for a long-running operation.
• task_id remains the raw Proxmox UPID and can change when a job is retried.
• Job records persist in the configured SQLite database and survive process restart.
• retry_job only works when the job was created with a stored retry recipe.
• cancel_job is best-effort and follows Proxmox task cancellation semantics.

OpenAPI Job Status Codes

• 200: list, fetch, or poll succeeded
• 202: cancel or retry request accepted
• 404: unknown job_id
• 409: the job exists but cannot perform that action now
• 503: the OpenAPI wrapper has no local JobStore

Common Prerequisites

• Mutating tools assume the target node, VM, container, storage pool, or archive already exists unless the tool itself creates it.
• VM command execution requires a running VM with QEMU Guest Agent available.
• Container command execution requires SSH to the Proxmox host and a running target container.
• Backup restore uses a new target vmid; it is not an in-place overwrite workflow.

Container Selector Grammar

Several container tools accept a selector parameter. Supported forms:

• 123
• pve1:123
• pve1/name
• name
• comma-separated lists for bulk operations

Selector-based tools fail when no container matches the selector or when a bulk selector includes invalid targets.

Node Tools

Tool	Mode	Required Inputs	Optional Inputs	Prerequisites	Common Failures
get_nodes	Read-only	none	none	Proxmox API reachable	auth failure, API unavailable
get_node_status	Read-only	node	none	target node exists	unknown node, auth failure

VM Tools

Tool	Mode	Required Inputs	Optional Inputs	Prerequisites	Common Failures
get_vms	Read-only	none	none	Proxmox API reachable	partial node-query failures may reduce returned coverage
create_vm	Mutating	node, vmid, name, cpus, memory, disk_size	storage, ostype, network_bridge, pool	target node exists and selected storage is valid	duplicate vmid, invalid storage or resource pool, insufficient permissions or resources
clone_vm	Mutating	node, source_vmid, target_vmid	name, target_node, full=true, storage, pool, snapname	source VM exists and target VM ID is free	duplicate target VM ID, clone permission failure, invalid storage or snapshot
start_vm	Mutating	node, vmid	none	VM exists	VM not found, node mismatch
stop_vm	Mutating	node, vmid	none	VM exists	VM not found, stop failure from Proxmox
shutdown_vm	Mutating	node, vmid	none	VM exists	guest shutdown unavailable or timeout on guest side
reset_vm	Mutating	node, vmid	none	VM exists	VM not found, reset rejected by Proxmox
delete_vm	Mutating	node, vmid	force=false	VM exists	running VM without force, VM not found
execute_vm_command	Mutating	node, vmid, command	approval_token	VM running, QEMU Guest Agent installed, policy allows command	guest agent unavailable, VM not running, policy denial
get_vm_config	Read-only	node, vmid	none	VM exists	VM not found, node mismatch
set_vm_description	Mutating	node, vmid, description	none	VM exists and API token can update its config	VM not found, node mismatch, insufficient permissions

VM Notes

• stop_vm is the force-stop path. Use shutdown_vm for graceful guest shutdown when supported.
• execute_vm_command is not a generic SSH shell. It is mediated through QEMU Guest Agent and command-policy checks.
• create_vm.pool is an optional Proxmox resource pool, not a storage pool. Pool-scoped API tokens also need Pool.Allocate on the target pool.
• create_vm, clone_vm, start_vm, stop_vm, shutdown_vm, reset_vm, and delete_vm register persistent jobs when they return asynchronous Proxmox tasks.

Container Tools

Tool	Mode	Required Inputs	Optional Inputs	Prerequisites	Common Failures
get_containers	Read-only	none	node, include_stats=false, include_raw=false, format_style=pretty|json, legacy payload object	Proxmox API reachable	invalid payload shape, auth failure
start_container	Mutating	selector	format_style=pretty|json	selector resolves to one or more containers	no selector match, start failure from Proxmox
stop_container	Mutating	selector	graceful=true, timeout_seconds=10, format_style=pretty|json	selector resolves to one or more containers	no selector match, timeout on graceful shutdown, container already stopped
restart_container	Mutating	selector	timeout_seconds=10, format_style=pretty|json	selector resolves to one or more containers	no selector match, reboot failure
update_container_resources	Mutating	selector	cores, memory, swap, disk_gb, disk=rootfs, format_style=pretty|json	selector resolves to one or more containers	no selector match, invalid resize target, resource update rejected
create_container	Mutating	node, vmid, ostemplate	hostname, cores=1, memory=512, swap=512, disk_size=8, storage, password, ssh_public_keys, network_bridge=vmbr0, start_after_create=false, onboot=false, nesting=false, unprivileged=true, pool	target node exists, template path valid, target storage valid	duplicate vmid, missing template, invalid storage, resource pool, or bridge
delete_container	Mutating	selector	force=false, format_style=pretty|json	selector resolves to one or more containers	no selector match, running container without force, delete failure
execute_container_command	Mutating	selector, command	approval_token	only registered when ssh config exists; container must be running; policy must allow command	tool unavailable without SSH config, no selector match, SSH failure, policy denial
update_container_ssh_keys	Mutating/high-risk	node, vmid, public_keys	mode=append|replace, approval_token	only registered when ssh config exists; target container reachable through configured execution path; high-risk policy must allow the operation	tool unavailable without SSH config, invalid container target, SSH failure, approval required
get_container_config	Read-only	node, vmid	none	target container exists	container not found, node mismatch
set_container_description	Mutating	node, vmid, description	none	target container exists and API token can update its config	container not found, node mismatch, insufficient permissions
get_container_ip	Read-only	node, vmid	none	target container exists	container not found, IP information unavailable

Container Notes

• get_containers exposes flat top-level parameters for stricter MCP clients. The legacy payload object is still accepted for existing callers.
• update_container_resources.disk_gb is an additional resize amount for the selected disk, not a full replacement size target.
• create_container.start_after_create controls immediate startup after provisioning.
• create_container.nesting and create_container.unprivileged change container execution characteristics and should match your Proxmox policy.
• create_container.pool is an optional Proxmox resource pool, not the storage used for rootfs. Pool-scoped API tokens also need Pool.Allocate on the target pool.
• create_container, start_container, stop_container, restart_container, and delete_container create persistent job records for asynchronous task tracking.

Snapshot Tools

Tool	Mode	Required Inputs	Optional Inputs	Prerequisites	Common Failures
list_snapshots	Read-only	node, vmid	vm_type=qemu|lxc	target VM or container exists	wrong vm_type, missing target
create_snapshot	Mutating	node, vmid, snapname	description, vmstate=false, vm_type=qemu|lxc	target exists	duplicate snapshot name, unsupported vmstate use, wrong target type
delete_snapshot	Mutating	node, vmid, snapname	vm_type=qemu|lxc	snapshot exists	snapshot not found, wrong target type
rollback_snapshot	Mutating	node, vmid, snapname	vm_type=qemu|lxc	snapshot exists	snapshot not found, rollback rejected by Proxmox

Snapshot Notes

• rollback_snapshot is a disruptive restore action and should be treated as an operationally sensitive step.
• vmstate applies to VM snapshots and is not a general LXC memory-capture option.
• create_snapshot, delete_snapshot, and rollback_snapshot all register persistent jobs when Proxmox returns a task UPID.

ISO and Template Tools

Tool	Mode	Required Inputs	Optional Inputs	Prerequisites	Common Failures
list_isos	Read-only	none	node, storage	Proxmox API reachable	invalid node or storage filter
list_templates	Read-only	none	node, storage	Proxmox API reachable	invalid node or storage filter
download_iso	Mutating	node, storage, url, filename	checksum, checksum_algorithm=sha256	target storage writable and reachable by Proxmox	invalid URL, checksum mismatch, unsupported storage target
delete_iso	Mutating	node, storage, filename	none	file exists in target storage	file not found, storage mismatch

ISO and Template Notes

• list_templates is commonly used to discover a valid ostemplate value for create_container.
• When checksum is supplied, checksum_algorithm must match the provided digest.
• download_iso and delete_iso register jobs so callers can poll progress from the same job_id.

Backup Tools

Tool	Mode	Required Inputs	Optional Inputs	Prerequisites	Common Failures
list_backups	Read-only	none	node, storage, vmid	backup-capable storage reachable	invalid filter or storage mismatch
create_backup	Mutating	node, vmid, storage	compress=0|gzip|lz4|zstd, mode=snapshot|suspend|stop, notes	target workload exists and storage accepts backups	invalid mode, storage unavailable, backup job rejected
restore_backup	Mutating	node, archive, vmid	storage, unique=true	archive exists and target vmid is free	missing archive, duplicate target vmid, invalid target storage
delete_backup	Mutating	node, storage, volid	none	backup volume exists	volume not found, storage mismatch

Backup Notes

• restore_backup restores into a new vmid.
• create_backup.mode changes how Proxmox coordinates workload state during backup and may affect runtime interruption characteristics.
• create_backup, restore_backup, and delete_backup register persistent jobs and support later poll, cancel, and retry through the job surface.

Job Tools

Tool	Mode	Required Inputs	Optional Inputs	Prerequisites	Common Failures
list_jobs	Read-only	none	status, tool_name, limit=100	in-process JobStore enabled	job store unavailable
get_job	Read-only	job_id	refresh=false	job exists	unknown job_id
poll_job	Mutating	job_id	none	job exists and has a Proxmox UPID	unknown job_id, backend poll failure
cancel_job	Mutating	job_id	none	job exists and supports cancellation	unknown job_id, no UPID, cancel conflict
retry_job	Mutating	job_id	none	job exists and has a retry recipe	unknown job_id, no retry recipe, handler unavailable

Job Notes

• get_job(refresh=true) is the HTTP equivalent of calling poll_job.
• Completed jobs stay queryable until you remove the SQLite file or add retention logic.
• previous_upids records earlier Proxmox task IDs after retries.
• audit_log stores creation, polling, retry, and cancellation events for operator review.

Storage and Cluster Tools

Tool	Mode	Required Inputs	Optional Inputs	Prerequisites	Common Failures
get_storage	Read-only	none	none	Proxmox API reachable	auth failure, cluster query failure
get_cluster_status	Read-only	none	none	Proxmox API reachable	auth failure, cluster query failure

Log Inspection Tools

Tool	Mode	Required Inputs	Optional Inputs	Prerequisites	Common Failures
get_node_syslog	Read-only	node	limit=100, start, since, until, service	target node exists	unknown node, auth failure
get_task_log	Read-only	node, upid	start, limit=50	task exists on the node	unknown upid, node mismatch
get_cluster_log	Read-only	none	max_entries=50	Proxmox API reachable	auth failure, cluster query failure
get_node_firewall_log	Read-only	node	limit=100, start, since, until	target node exists	unknown node, firewall logging disabled yields few or no entries
get_guest_firewall_log	Read-only	node, vmid	vm_type=qemu|lxc, limit=100, start, since, until	guest exists on the node	unknown guest, wrong vm_type, guest firewall logging disabled

Log Inspection Notes

• All tools in this group are read-only and never modify Proxmox state.
• get_node_syslog.since/until take date/time strings (YYYY-MM-DD[ HH:MM[:SS]]); the firewall variants take UNIX epoch integers.
• get_task_log accepts any Proxmox task UPID (for example the Task ID returned by mutating tools), while poll_job operates on the persistent job records created by this server's mutating tools.
• Log content is returned as-is from Proxmox and may include sensitive operational details; scope API token permissions accordingly.

Change Checklist For New Tools

When adding or changing a tool, update all of the following:

• tool implementation under src/proxmox_mcp/tools/
• registration in the built-in plugin layer under src/proxmox_mcp/services/builtin_tool_plugins.py
• human-facing description in src/proxmox_mcp/tools/definitions.py
• tests under tests/
• this page if parameters, prerequisites, or availability changed

Related Pages

• Operator Guide
• Security Guide
• Container Command Execution
• Integrations Guide
• Troubleshooting