pterodactyl-mcp

Send a Pterodactyl console command

ptero_send_console_command

Destructive

Dispatch a command to a running Pterodactyl server console. Use with ptero_get_console_log to read the output, since the command result is not returned. Prefer ptero_set_power_state for power changes.

Instructions

Send a command to the server console via the panel's command endpoint (the panel forwards it to the running process). This confirms DISPATCH ONLY — it does NOT return the command's output. Wings does not correlate console output with the command that produced it, so there is no request/response shape to report here, faked or otherwise: the output is asynchronous. Call ptero_get_console_log immediately afterwards (a window_seconds of 3-5 is usually enough) to read what the command did.

Do not use this to stop, restart or kill the server. A command like stop will shut it down, but ptero_set_power_state is the correct, guarded way to change power state and should be preferred for that.

The panel answers with HTTP 502 when the target server is offline, since console commands require a running server — that is reported back as an actionable error telling you to start the server with ptero_set_power_state first.

Input Schema

TableJSON Schema

Name	Required	Description
`server`	No	Server short identifier (e.g. 1a2b3c4d). Omit to use PTERODACTYL_DEFAULT_SERVER. Call ptero_list_servers to discover valid identifiers.
`command`	Yes	The exact command to send, as you would type it at the console (no leading `/`). 1-4096 characters, a single line, trimmed of surrounding whitespace.
`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.

Output Schema

TableJSON Schema

Name	Required	Description
`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.
`command`	No	The exact command that was dispatched.
`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.
`dispatched`	No	True once the panel accepted the command for delivery to the daemon.
`expires_in_s`	No
`confirmed_via`	No
`confirmation_token`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 26, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already mark this as destructive and non-read-only, but the description adds substantial behavioral context: the action is asynchronous, output is not correlated by Wings, no request/response shape exists, and the panel returns HTTP 502 when the server is offline. This goes well beyond the structured annotation fields and does not contradict them.

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 action and then uses every remaining sentence for a high-value caveat: dispatch-only semantics, the follow-up log call, the power-state alternative, and the offline error behavior. Nothing feels redundant or promotional; the length is justified by the tool's async and destructive nature.

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?

Given the tool's complexity—async console dispatch, destructive potential, and offline failure mode—the description covers all essential operational context: what is returned, what is not returned, how to observe results, which sibling tool to use for power state, and how offline errors are reported. An output schema exists, so not detailing return fields is acceptable.

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

Parameters3/5

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

Schema description coverage is 100%, with all three parameters (server, command, dry_run) already documented in detail. The description adds a relevant example command (`stop`) and mentions `window_seconds` for the follow-up log call, but it does not need to restate parameter meanings. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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 description opens with a specific verb and resource: 'Send a command to the server console via the panel's command endpoint.' It also clarifies the exact scope of the action by stating it is 'DISPATCH ONLY' and does not return command output, which clearly distinguishes it from ptero_get_console_log and ptero_set_power_state.

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?

The description gives explicit usage guidance: call ptero_get_console_log immediately afterwards to read output, do not use this tool to stop/restart/kill the server, and prefer ptero_set_power_state for power changes. It also explains the offline 502 behavior and directs the agent to start the server first. This leaves no ambiguity about when to use this tool versus alternatives.

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