Using Minecraft 26.2 Server Management Protocol 3.0.0 Safely
Published and official references checked 2026-08-29 · SameOS operator
RCON is convenient when an automation only needs to send console command strings, but its output then has to be parsed. Minecraft Server Management Protocol exchanges structured JSON for players, allowlists, operators, game rules, and server state. It first appeared in 1.21.9 and is version 3.0.0 in 26.2, so the safe starting point is the schema reported by the running server rather than a method list copied from an older guide.
How It Differs From RCON
RCON remains the shortest path for existing console commands such as say, save-all, and whitelist. The management protocol uses JSON-RPC 2.0 over WebSocket: each request separates its id, method, and parameters, and a persistent client can receive notifications such as player joins and game-rule changes.
Protocol 3.0.0 in Minecraft 26.2 starts the management server before the game world finishes loading. rpc.discover and server-status notifications are available early, while methods that require the world can return a not-ready error. An automation must not treat an open TCP port as proof that the world is ready for players or mutations.
Bind server.properties to Localhost
Keep the first setup on the same machine by binding the service to 127.0.0.1. Port 0 selects a free port on every start, which is awkward for a supervised client, so this example explicitly chooses 25585. TLS is disabled only for this loopback-only connection; bearer authentication is still required.
management-server-secret must contain exactly 40 ASCII letters and digits. The server can generate one when the property is empty, but a stable client is easier to manage when you generate and store the secret in a private configuration. Never put it in Git, browser JavaScript, a screenshot, or a support log.
# Generate 40 characters, then copy the output into a private setting
tr -dc 'A-Za-z0-9' </dev/urandom | head -c 40; echo
# server.properties
management-server-enabled=true
management-server-host=127.0.0.1
management-server-port=25585
management-server-secret=[REPLACE_WITH_THE_40_CHARACTER_TOKEN]
management-server-tls-enabled=false
status-heartbeat-interval=10The bracketed placeholder is deliberately invalid. Replace it with the generated 40-character alphanumeric token before restarting the server.
Ask rpc.discover Before Calling Anything Else
Methods and parameter shapes can move between protocol releases. Treat the current server response to rpc.discover as authoritative. Connect with a WebSocket client such as websocat, supply the bearer token as an Authorization header, and send the JSON line below.
The result describes the methods, notifications, and parameter schemas implemented by that exact build. Saving this result also gives you a small compatibility diff to review before and after each Minecraft server upgrade.
# Avoid exposing TOKEN in screen shares and shell history
read -rsp 'Management token: ' TOKEN; echo
websocat -H="Authorization: Bearer ${TOKEN}" ws://127.0.0.1:25585
# Send after the connection opens
{"jsonrpc":"2.0","id":1,"method":"rpc.discover"}Allowlist Calls and the Not-Ready State
The official 1.21.9 example passes an array of names to minecraft:allowlist/add. On a 26.2 server, first confirm that method and its parameter schema in rpc.discover, then call it. Both successful and failed responses carry the request id, allowing a client to match concurrent results without scraping console text.
When a world-dependent method fails during startup, wait for server status or retry with backoff instead of hammering the socket. Record disconnect, authentication failure, missing method, and world-not-ready as different states; collapsing them into one “offline” message makes operations much harder to debug.
{"jsonrpc":"2.0","id":2,"method":"minecraft:allowlist/add","params":[[{"name":"PLAYER_NAME"}]]}
# Confirm that the port is not listening on a public address
ss -ltn | grep ':25585'
# Expected: 127.0.0.1:25585 (stop if it shows 0.0.0.0:25585)The Boundary for Remote Administration
This is an administrative control plane that can save and stop the server and change operators and allowlists. Do not forward it like a gameplay port. If remote administration is necessary, carrying the loopback connection through an SSH tunnel or an authenticated private VPN is easier to reason about.
Protocol 2.0.0 added browser authentication through Sec-WebSocket-Protocol plus an allowed-origin setting, but a token embedded in public front-end code is still visible to visitors. Keep public pages away from the management socket. If you build a server-side bridge, add your own method-level authorization rather than turning it into a transparent proxy.
- Bind the management port only to 127.0.0.1 or a private VPN address.
- Use separate tokens per environment and exclude them from logs and Git.
- Save a fresh rpc.discover schema after every server update.
- Make save and stop workflows idempotent before automatic retries.
Verification scope and official references
This guide cross-checks the initial 1.21.9 protocol notes, the 2.0.0 changes in 1.21.11, and the 3.0.0 startup behavior in 26.2. WebSocket client flags vary by package version, so confirm the header option with websocat --help. No production token or private server address is used here.