How to Connect Your Minecraft Server to MineKeep

Connect your WinterNode Minecraft server to MineKeep, a server listing and discovery platform, by pointing your server at MineKeep’s session server for player authentication.

Choose your setup based on whether you need direct connections to remain working:

Option 1: Paper Standalone

The simplest setup. Your existing Paper server is configured to use MineKeep’s session server via JVM flags. No extra servers required.

Direct connections will stop working — MineKeep’s session server only authenticates players joining through their platform. If you need direct access too, use the Two Velocity Proxies option instead.

1. Set the JVM flags

1. In the Game Control Panel, go to Configuration → Server Options
2. Find the JVM Flags field
3. Add the following flags (all on one line):

-Dminecraft.api.auth.host=https://authserver.mojang.com/ -Dminecraft.api.account.host=https://api.mojang.com/ -Dminecraft.api.services.host=https://api.minecraftservices.com/ -Dminecraft.api.profiles.host=https://api.mojang.com/ -Dminecraft.api.session.host=https://sessionserver.minekeep.net

4. Click Save

2. Update server.properties

1. Open File Manager and find server.properties in your root directory
2. Set:

enforce-secure-profile=false

3. Save the file and restart your server

3. Complete MineKeep registration

Follow MineKeep’s external server setup to register your server and verify players can connect through MineKeep.

Option 2: Velocity Proxy

Use this if you already run Velocity, or prefer a proxy setup. Like Paper Standalone, direct connections will not work with this option — HAProxy is required for MineKeep but disables direct connections on the same proxy.

Requires one separate server running Velocity. Order a 2GB Minecraft server and select Velocity as the server software.

Once your Velocity server is running, follow the Velocity setup guide to connect your Paper server as a backend, then add the MineKeep JVM flag to your Velocity server:

1. On your Velocity server, go to Configuration → Server Options → JVM Flags
2. Add:

-Dmojang.sessionserver=https://sessionserver.minekeep.net/session/minecraft/hasJoined

3. In velocity.toml, ensure HAProxy protocol is enabled:

haproxy-protocol = true

4. Complete MineKeep’s Velocity setup instructions to register your proxy

Option 3: Two Velocity Proxies

This option supports both MineKeep access and direct connections simultaneously, confirmed working via support testing. It requires two separate Velocity servers plus your Paper backend — three servers total.

• Proxy A — dedicated to MineKeep (HAProxy on, MineKeep JVM flag, registered with MineKeep)
• Proxy B — dedicated to direct connections (no HAProxy, no JVM flag, subdomain points here)
• Paper backend — same backend for both proxies

1. Set up Proxy A (MineKeep proxy)

Follow the Velocity setup guide to create a Velocity server and connect your Paper backend to it, then:

1. In velocity.toml, set:

player-info-forwarding-mode = "modern"
haproxy-protocol = true

2. In Configuration → Server Options → JVM Flags, add the MineKeep flag:

-Dmojang.sessionserver=https://sessionserver.minekeep.net/session/minecraft/hasJoined

3. Note the contents of the forwarding.secret file — you’ll need this for Proxy B and Paper

4. Register Proxy A with MineKeep following their Velocity instructions

2. Set up Proxy B (direct connection proxy)

1. Order a second 2GB Minecraft server and select Velocity
2. Start it once to generate config files, then stop it
3. In velocity.toml, configure it identically to Proxy A except:

player-info-forwarding-mode = "modern"
haproxy-protocol = false   # Do NOT enable — this is what allows direct connections

4. Under [servers], use the same Paper backend IP and port as Proxy A:

[servers]
lobby = "your.paper.ip:port"

5. Copy the forwarding.secret file from Proxy A to Proxy B (or set the same secret value) — both proxies must share the same secret since they connect to the same Paper backend

6. Add your custom subdomain (e.g., play.yourserver.com or your playwn.co subdomain) to Proxy B — this is the address players use for direct connections

3. Configure the Paper backend

Paper only needs to be configured once — both proxies share the same secret:

1. Open config/paper-global.yml on your Paper server:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "paste-the-contents-of-forwarding.secret-here"

2. Open server.properties on your Paper server:

online-mode=false

3. Restart your Paper server

Troubleshooting

Direct connection times out after Paper Standalone or Velocity setup

This is expected. MineKeep’s session server only authenticates players joining through their platform, and HAProxy protocol (required by MineKeep’s Velocity setup) blocks direct client connections. Use the Two Velocity Proxies option if you need both.

Backend server is online-mode!

java.lang.IllegalStateException: Backend server is online-mode!

Your Paper server.properties still has online-mode=true. Set it to false — the proxy handles authentication.

Player info forwarding is disabled

WARN: Player info forwarding is disabled! All players will appear to be connecting from the proxy and will have offline-mode UUIDs.

The velocity section in Paper’s config/paper-global.yml has enabled: false. Set it to enabled: true and restart Paper.

Unable to verify player details

ERROR: disconnected while connecting to lobby: Unable to verify player details

The forwarding secret doesn’t match between Velocity and Paper. Open the forwarding.secret file on your Velocity server, copy its contents, and paste the value into the secret: field in Paper’s config/paper-global.yml. Restart both servers.

This server requires you to connect with Velocity

Paper has modern forwarding enabled but Velocity isn’t configured to use it, or the secrets don’t match. Confirm player-info-forwarding-mode = "modern" is in velocity.toml and the secret matches on both sides.

You are not logged into your Minecraft account

The MineKeep JVM flag is missing from your Velocity server. Go to Configuration → Server Options → JVM Flags on your Velocity server and add the -Dmojang.sessionserver flag from Option 2 above.

Connection refused to backend

Connection refused: your.ip:port

The IP or port in velocity.toml under [servers] is wrong. Check Management → Allocations on your Paper server for the correct values and update velocity.toml. After moving a subdomain from Paper to Velocity, make sure velocity.toml uses the raw IP (e.g., 104.128.51.159:25579), not the subdomain — otherwise Velocity will try to resolve the subdomain back to itself.

Failed to verify username (Paper Standalone)

Failed to verify username!
Username 'PlayerName' tried to join with an invalid session

1. Verify all five JVM flags are present — copy the full block from Option 1 and confirm none are missing
2. Check flag placement — flags must go in the JVM Flags field, not after the jar filename
3. Remove trailing slash — use https://sessionserver.minekeep.net not https://sessionserver.minekeep.net/
4. Confirm enforce-secure-profile=false is set in server.properties
5. Restart fully — JVM flag changes require a complete server restart