pterodactyl-mcp

Create a Pterodactyl backup

ptero_create_backup

Take an immediate server backup to create a rollback point before file changes or power operations. Waits for completion by default, returns size and status.

Instructions

Take a backup of the server right now. Safe. The natural thing to do BEFORE any file write, delete, or power kill — it gives you a rollback point.

By default (wait: true) this blocks until the panel reports the backup complete (polling for up to two minutes) and returns its final size and success state. Pass wait: false to return immediately with just the uuid if you do not want to block; check completion later with ptero_list_backups.

The panel enforces a per-server backup-count limit; creation fails with an actionable error when the server is full — the fix is ptero_delete_backup on an old one, not a retry.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	Backup name. Omit to let the panel assign a default name.
`wait`	No	Wait for the backup to finish before returning (up to ~2 minutes). false returns immediately with just the uuid — check ptero_list_backups for completion.
`server`	No	Server short identifier (e.g. 1a2b3c4d). Omit to use PTERODACTYL_DEFAULT_SERVER. Call ptero_list_servers to discover valid identifiers.
`dry_run`	No	When true, validate and preview the change without performing it. Nothing is modified and no confirmation token is issued. Use this to reason about an operation before committing to it.
`ignored`	No	Newline-separated list of glob patterns to exclude from the backup, e.g. "cache/*\n.log".

Output Schema

TableJSON Schema

Name	Required	Description
`name`	No
`uuid`	No
`bytes`	No
`reason`	No	Why the call was refused.
`server`	Yes
`status`	Yes	success = the change was made. refused = a guardrail blocked it (see reason/variable). dry_run = nothing changed; preview shows what would. needs_confirmation = nothing changed; SHOW the preview to the human and, only if they agree, call again with confirmation_token.
`message`	No
`preview`	No	What would / did change.
`variable`	No	Environment variable that caused the refusal.
`backup_id`	No	UUID of the automatic pre-change backup, if one was taken.
`completed`	No	True once the backup has finished (only when wait:true).
`waited_ms`	No	Milliseconds spent polling for completion (only when wait:true).
`bytes_human`	No
`completed_at`	No
`expires_in_s`	No
`confirmed_via`	No
`is_successful`	No
`confirmation_token`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 26, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only provide flags, so the description carries the behavioral burden. It discloses blocking/polling behavior up to two minutes, return behavior differences between wait:true and wait:false, the per-server backup-count limit, and the actionable error path when full. The phrase 'Safe' aligns with destructiveHint=false and no contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and use case, then adds wait behavior and failure handling in clearly separated paragraphs. Every sentence contributes useful context, with no filler or repetition beyond what is needed for operational clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers when to use the tool, the main behavioral modes, and the key failure condition. Combined with the fully documented input schema and the presence of an output schema, an agent has everything needed to invoke it correctly without ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful meaning for the wait parameter: it explains polling, the final size and success state, and the immediate uuid-only return path. It also adds operation-level context about the backup-count limit that affects whether creation can succeed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Take a backup of the server right now.' It frames the tool as a rollback step before file writes, deletes, or power kills, which clearly distinguishes it from sibling backup tools like ptero_list_backups, ptero_delete_backup, and ptero_get_backup_download_url.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it: before any file write, delete, or power kill, to create a rollback point. It also names alternatives: ptero_list_backups for checking completion when wait:false, and ptero_delete_backup as the fix when the per-server backup limit is full, with an explicit 'not a retry' warning.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.