How to Connect Your Minecraft Server to Minehut

Connect your WinterNode Minecraft server to Minehut, a Minecraft server listing and community platform, by pointing your server at Minehut’s authentication service.

There are two main ways to connect your server, depending on whether you want to run a proxy:

Option 1: Paper Standalone

This option requires no proxy. You configure your Paper server to use Minehut’s session server directly via JVM flags.

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.services.host=https://api.minecraftservices.com/ -Dminecraft.api.auth.host=https://authserver.mojang.com/ -Dminecraft.api.account.host=https://api.mojang.com/ -Dminecraft.api.profiles.host=https://api.mojang.com/ -Dminecraft.api.session.host=https://api.minehut.com/mitm/proxy

4. Click Save

2. Update server.properties and paper-global.yml

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

enforce-secure-profile=false

3. Open config/paper-global.yml and set the following under proxies:

proxies:
  proxy-protocol: true

4. Save both files

3. Restart and configure Minehut

1. Restart your server
2. In the Minehut panel, navigate to External Server Settings and fill in your server’s public IP, port, proxy type (Other for Paper Standalone), and DNS record type
3. Connect through Minehut to verify players can authenticate

Option 2: Velocity Proxy

Use this option if you already have Velocity set up, or want a proxy in front of your server. This requires two separate servers: one running Velocity and one running Paper.

If you haven’t set up Velocity yet, order a separate 2GB Minecraft server and select Velocity as the server software. Then follow the Velocity setup guide to connect your Paper server as a backend.

Once Velocity is set up and your Paper server is connected behind it:

1. Add the Minehut JVM flag to Velocity

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

-Dmojang.sessionserver=https://api.minehut.com/mitm/proxy/session/minecraft/hasJoined

3. Save and restart your Velocity server

2. Enable HAProxy protocol in Velocity

Without this, all players appear to connect from the same IP address, breaking IP bans and player tracking:

1. Open File Manager on your Velocity server and find velocity.toml
2. Under the [advanced] section, set:

haproxy-protocol = true

3. Save the file and restart Velocity

3. Configure Minehut panel

In External Server Settings on Minehut, set the proxy type to Velocity and enter your Velocity server’s public IP and port. Minehut will forward player connections through your Velocity proxy to your backend Paper server.

Option 3: Waterfall

Waterfall is supported if you’re already running it. The setup is the same as Velocity with different flag syntax:

JVM flag (add to your Waterfall server’s JVM Flags field):

-Dwaterfall.auth.url="https://api.minehut.com/mitm/proxy/session/minecraft/hasJoined?username=%s&serverId=%s%s"

config.yml (under listeners):

proxy_protocol: true

Set the proxy type to Waterfall in Minehut’s External Server Settings.

Troubleshooting

Failed to verify username

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

This means Minehut’s session server isn’t authenticating the player. Check the following:

1. Verify all five JVM flags are present — copy the full block from Option 1 above and confirm none are missing
2. Check flag placement — flags must go in the JVM Flags field, not appended after the jar filename in the startup command
3. Confirm enforce-secure-profile=false is set in server.properties (Paper Standalone only)
4. Confirm proxy-protocol: true is set in config/paper-global.yml (Paper Standalone only)
5. Restart fully after saving — changes to JVM flags require a complete server restart to take effect