How to Configure Minecraft Server Management Protocol 3.0.0

Minecraft Java Edition 26.2 identifies its server-management interface as Management Protocol 3.0.0. In this version, the management server starts before.

How to Configure Minecraft Server Management Protocol 3.0.0

Minecraft Java Edition 26.2 identifies its server-management interface as Management Protocol 3.0.0. In this version, the management server starts before the Minecraft server, allowing heartbeats during world loading or upgrades and early access to rpc.discover and notification/server/status.

1. Enable a predictable endpoint

The management API is disabled by default. Its host defaults to localhost, and port 0 assigns an available port whenever the management server starts. For a local management client that needs a stable port, an operator can use:

management-server-enabled=true
management-server-host=127.0.0.1
management-server-port=25585

The address and port above are operator-selected examples, not Minecraft defaults. Confirm that the chosen port is available and limit network access according to the deployment's requirements.

2. Configure bearer authentication

Management clients must authenticate using an Authorization bearer-token header containing the server-specific secret:

Authorization: Bearer <management-secret>

The secret is configured through management-server-secret. Mojang states that it should be exactly 40 alphanumeric characters using A-Z, a-z, and 0-9; leaving the property empty causes the server to generate it automatically. Unauthorized requests receive 401 Unauthorized.

management-server-secret=<40-alphanumeric-characters>

Store the secret outside source control and redact it from logs, command output, and documentation.

3. Configure TLS and a PKCS12 keystore

TLS defaults to enabled. Mojang's release notes require a configured PKCS12 keystore when TLS is enabled and state that the dedicated server will not start without one.

management-server-tls-enabled=true
management-server-tls-keystore=/srv/minecraft/secrets/management.p12

The keystore password can be supplied through these mechanisms, in descending priority:

1. MINECRAFT_MANAGEMENT_TLS_KEYSTORE_PASSWORD environment variable
2. -Dmanagement.tls.keystore.password=... JVM argument
3. management-server-tls-keystore-password=... server property

Prefer a service-manager or secret-store facility and keep access to the keystore restricted.

4. Discover the running API

The management interface uses JSON-RPC over WebSocket. Mojang documents rpc.discover as returning an API schema containing the methods and notifications supported by the running server:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "rpc.discover"
}

Use the returned schema instead of assuming that a method or parameter structure is available after an upgrade.

Under JSON-RPC 2.0, the server returns the request's id in its response. A response contains either result or error, never both. A notification has no id, and the server does not return a response for it.

5. Test a documented method

Mojang documents this positional-parameter example for adding jeb_ to the allowlist:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "minecraft:allowlist/add",
  "params": [
    [
      {
        "name": "jeb_"
      }
    ]
  ]
}

Its documented successful result contains the resolved name and UUID:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": [
    {
      "id": "853c80ef-3c37-49fd-aa49-938b674adae6",
      "name": "jeb_"
    }
  ]
}

Treat the operation as successful only after receiving a matching response with result. Preserve sanitized error codes and messages when an error response arrives, and avoid blindly retrying state-changing requests.

6. Handle notifications

The official release notes provide this player-joined notification example:

{
  "jsonrpc": "2.0",
  "method": "minecraft:notification/players/joined",
  "params": [
    {
      "id": "853c80ef-3c37-49fd-aa49-938b674adae6",
      "name": "jeb_"
    }
  ]
}

Keep the WebSocket open and dispatch notifications by their discovered method names. Validate their parameters and handle unknown notifications without terminating the client.

7. Monitor startup

The status-heartbeat-interval property controls heartbeat notifications and defaults to 0, which disables them. Choose and test a nonzero interval appropriate for the monitoring system:

status-heartbeat-interval=5

With Protocol 3.0.0, heartbeats can arrive while the world is loading or potentially upgrading. During that early phase, rpc.discover and notification/server/status are accessible, while calls to other methods return an error. Clients should therefore treat management connectivity and Minecraft readiness as separate states and defer administrative writes until startup is complete.

After an upgrade, repeat discovery and a harmless read test before enabling automated writes. For community-oriented updates, you can follow sourced Minecraft coverage on TOP OF GAMES, while using Mojang's release notes and the live discovery schema as the technical references.