Skip to main content
Glama
N1jada

pterodactyl-mcp

by N1jada
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Set Pterodactyl server power state

ptero_set_power_state
Destructive

Control a Pterodactyl game server's power state: start, stop, restart, or kill the process, with confirmation and rate limiting for safe operation.

Instructions

Send a power signal to the server. start boots it from offline. stop gracefully shuts it down, saving the world first, and disconnects any connected players. restart stops then starts it again, briefly disconnecting players. kill forcibly terminates the process immediately, without saving.

kill is a hard stop and risks world corruption: prefer stop in almost every case, and reach for kill only when the server is hung and unresponsive to a normal stop. kill additionally refuses to run unless PTERODACTYL_ALLOW_KILL=true is set, and when it does proceed an automatic backup is taken first (the kill is aborted if that backup fails).

stop, restart and kill are destructive and require explicit human confirmation before they run — via MCP elicitation where the client supports it, otherwise a two-phase confirmation_token. On the first call (no token) nothing changes: you get back a preview of the current state and what the signal will do. THIS PREVIEW IS FOR THE HUMAN — show it in your reply and wait for their decision; do not silently call the tool again with the token yourself. Only call again, with the same arguments plus confirmation_token, once the human has approved it. start needs no confirmation.

Power actions are rate-limited to one per 30 seconds regardless of signal, to stop restart loops — a second power call inside that window is refused, naming how long to wait.

Set wait_seconds (0-60, default 0) to poll the live power state every 2 seconds after the signal is dispatched and report it back as state_after, instead of returning immediately with only the signal that was sent.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
serverNoServer short identifier (e.g. 1a2b3c4d). Omit to use PTERODACTYL_DEFAULT_SERVER. Call ptero_list_servers to discover valid identifiers.
signalYesPower signal to send. start = boot; stop = graceful shutdown (disconnects players); restart = stop then start (disconnects players); kill = hard-kill the process (risks world corruption — prefer stop).
dry_runNoWhen 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.
wait_secondsNoAfter dispatching the signal, poll the power state every 2 seconds for up to this many seconds (0-60, default 0 = do not wait) and report the final state as `state_after`.
confirmation_tokenNoTwo-phase confirmation token. Leave this out on the first call: the tool will refuse to act and instead return a preview of exactly what would change, plus a single-use token that expires in 120 seconds. THE PREVIEW IS FOR THE HUMAN — show it to the user in your reply and let them decide. Do not silently round-trip the token back in an immediate second call. Only call again with the token once the user has seen the preview and approved it. The token is bound to a hash of these exact arguments, so changing any argument invalidates it.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
reasonNoWhy the call was refused.
serverYes
signalNoThe power signal that was sent. Present only on `status: "success"`.
statusYessuccess = 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.
messageNo
previewNoWhat would / did change.
variableNoEnvironment variable that caused the refusal.
backup_idNoUUID of the automatic pre-change backup, if one was taken.
state_afterNoDaemon power state after polling for `wait_seconds`. Only present when `wait_seconds` was greater than 0.
expires_in_sNo
confirmed_viaNo
previous_stateNoDaemon power state captured immediately before the signal was dispatched (offline/starting/running/stopping/unknown). Present only on `status: "success"`.
confirmation_tokenNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Beyond destructiveHint=true, it discloses that stop/restart/kill require confirmation, the first call is preview-only, kill is gated behind an environment variable plus auto-backup and aborts if the backup fails, and power actions are rate-limited. This adds substantial non-obvious behavior not visible from annotations alone.

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?

Although long, every paragraph carries a distinct safety or workflow fact, and the most critical warnings (kill risk, confirmation, preview) are front-loaded. Paragraph breaks keep it scannable rather than a wall of text.

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?

For a destructive, confirmation-gated, rate-limited tool with five parameters and an output schema, this description is complete: an agent knows when to act, what will happen, what can go wrong, how to confirm, and what wait_seconds changes about the return value.

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?

The schema already covers all five parameters with 100% description coverage, so the baseline is high. The description still adds real value by explaining world-saving semantics for stop, corruption risk for kill, the preview/two-phase token contract, and the state_after polling effect of wait_seconds.

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?

The opening sentence pins the action to a specific verb ('Send a power signal') and resource ('the server'), and the four signal names make the scope unmistakable. It is clearly distinct from the sibling read, file, backup, and console-command tools.

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?

It gives explicit operational rules for choosing signals: prefer stop, use kill only when hung, and start needs no confirmation. It also explains the two-phase confirmation workflow and rate limit, so an agent knows exactly when to call, when to wait, and when to avoid the tool.

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

Deploy Server

Other Tools