Skip to main content
Open menu Close menu
  1. Minecraft Education
  2. Get Set Up
  3. Servers

Articles in this section

Dedicated Server Tooling and Scripting Guide

Justin Support Agent
  • Updated
Moderator Super Star Bug Zapper Support Beacon of Knowledge

For general information about the EDU Dedicated Server, please refer to the Dedicated Server FAQ article. In addition to our guide below, feel free to check out our video guide:

Note: Cross tenant play is currently unavailable. We hope to have this out in the near future! You will see the options to enable it in the Admin Portal where the setting will apply once available.

Step 1: Download files to the appropriate machines

  1. Download and install the client build(s) on your user machine(s):
  2. Download the dedicated server build(s) on your server machine(s):
  3. Download VS Code and the sample tooling Python notebook on your admin machine:

Step 2: Set up a Dedicated Server

Ensure your server meets our Dedicated Server System Requirements


Step 3: Create and configure a dedicated server

Dedicated server setup and sign in

  1. Unzip the server zip file.
  2. Acquire the IP and configure the port to which your client machines will connect.
    • If the client machines will be on the same network as the server machine, use the server machine’s local IP.
      • Windows: run the terminal command ipconfig
      • Linux: run the terminal command ip address
    • If the client machines will be on a different network than the server machine, use the server machine’s public IP.
      • Windows and Linux: run the terminal command curl ip.me
      • Ensure the port you want to host on is forwarded to the public internet.
  3. Ensure there are no firewalls on the client or server machines that will block clients from connecting to the server machine on the port you will be hosting.
  4. Configure the “server.properties” file:
    • Set the “server-public-ip” to the IP from above
    • Set the “server-port” to the port on which you want the server to host
  • Tip: It is recommended to not use default port of 19132
  • Set the “gamemode”, “difficulty”, “allow-cheats”, “chat-restriction”, “max-players”, “allow-list”, and other properties in the file as desired.
  • If “allow-list” is set to true, the “allowlist.json” file will need to be edited to include the details of any users expected to join (see the “Dedicated server allow list configuration” section below for more details).

Authenticate the server

  1. Run the server executable.
    • Windows: “bedrock_server.exe”
    • Linux: “bedrock_server_edu”
  2. In the output written to the terminal, follow the instructions to sign in with an admin account for your tenant (if on a headless OS, follow the instructions on a device with a browser).
    • The output to look for in the terminal looks like this
    • For more details on the browser sign in process, see the steps in the “Reference A: Device code browser sign in” section below.
    • A brief moment after completing the browser sign in, the server should complete the sign in process and present you with the server ID and tenant ID you signed in to, as well as the IP and port clients will use to try to connect to the server as configured in the “server.properties” file.
      • If your server closes and is run again, it will attempt to refresh your sign in silently using the information in the “edu_server_session.json” file, but if refreshing silently fails, it may prompt you to sign in again with the same steps you just went through.

      • Take note of the server ID printed in the output. You will need it later for the tooling to configure and enable the server’s visibility and name in clients.

      • If you lose track of the server ID, you can find it again in your “edu_server_session.json” file.

  3. At this point, the server is registered and hosted. However, before clients can connect, various additional properties that do not live in the server files must be configured. To see how these are set, see the “Tooling setup and sign in” section below.

Allow-list configuration

  1. To explicitly specify which users can join the server, you can set “allow-list” to true in the “server.properties” file and restart the server if it is running.

    • By default, there are no entries in the “allowlist.json” file.

    • As a result, if “allow-list” is set to true in the “server.properties” file, no users will be able to join the server and will be told they are banned if they attempt.

  2. To add a user to the allow list, edit the “allowlist.json” and restart the server if it is running.

    • If the user whose access you are trying to change has joined in the past, their access will already be saved in the JSON file.

    • If preventing a specific user from joining is desired, remove the entry containing that user’s name and/or ID from the file.

    • If allowing a specific user to join is desired, add an entry containing that user’s name and/or ID to the file in the following format.

Manage servers: Sample tooling

The sample tooling features a set of actions in a Jupyter Notebook that you can run to manage your servers. Using the notebook, you will be able to:

  • See and manage your existing servers and server properties
  • Name servers
  • Set and unset server passcodes
  • Delete servers
  • Invite other tenants to join a server in your tenant for cross-tenant play

 

Tooling setup and sign in

  1. On the admin machine where you downloaded VS Code and the sample tooling, install VS Code.

  2. Open the sample tooling in VS Code.

  3. Follow the instructions to set up VS Code for Jupyter Notebooks in VS Code.
    • Note that while you can run through the setup steps in a new notebook, you do not need to create a new notebook, since the sample tooling notebook is already provided.

  4. Ensure you have a minimum of Python 3.12 installed and that VS Code has the correct kernel selected.

  5. Run the first cell.

  6. In the output underneath the first cell, follow the instructions to sign in with an admin account for your tenant.

    • First, copy the code, then click the link.

    • Next, follow the steps in the “Reference A: Device code browser sign in” section below.
    • A brief moment after completing the browser sign in, the sample tooling should complete the sign in process and present you with the account name and tenant ID you signed in to, as well as the expiration date and time of the sign in session.
      • If your token expires, running the cell again may silently refresh your sign in or may prompt you to sign in again with the same steps you just went through.
  7. At this point, the notebook is ready to start configuring server registrations, which are the entries in Minecraft Education’s services that will be used to communicate the details of your servers to clients when users visit the Servers menu.

Tooling tenant settings

  1. Tenant settings can conveniently be edited via the Dedicated Server Admin Web Portal, but you can also use the sample tooling or write your own tooling to call the tenant settings endpoints. This can be useful if you want to automate or schedule changes and have a program make the changes for you.
  2. Similarly to the other cells in the notebook, there are placeholder values for various fields. Of special note however is the fact that the tooling/fetch_tenant_settings endpoint will return the IDs of any servers you have set to be broadcasted.

  3. The most important field in the tenant settings is "DedicatedServerEnabled", which must be set to True for users to see the Servers menu in the client or join servers.

Tooling basic usage

  1. If you haven’t already, go through the steps in the “Dedicated server setup and sign in” and “Tooling setup and sign in” sections. They are required before you can do anything meaningful with the sample tooling notebook.

  2. Start by running the tooling/fetch_all_server_ids cell.

    • If you get the "401 Unauthorized" error, you need to run the first cell again, because your access token has expired.
    • The result should include all the server IDs for which your tenant has registrations and thus to which your tenant has access to configure.
    • In the list of server IDs, you should see the ID of the server you set up in the “Dedicated server setup and sign in” section above. From here on out, we’ll refer to this server ID as the server ID of the server you are configuring, but you could also configure a different server by using its ID if you have another.

  3. Next, go to the tooling/fetch_server_info cell, change the placeholder “YourServerID” to the server ID of the server you are configuring, and run the cell.

    • A few important observations about the result:

      • The “isOwningTenant” property is true if your tenant registered the server and false if the server was shared with your tenant via the invite flow (see the “Tooling invite flow” section below for more details).
      • The “isEnabled” property defaults to false and must be set to true before users can join the server.

      • The “isBroadcasted” property defaults to false and if set to true, all users in your tenant will always see the server in the Servers menu, as long as the server is enabled. They will also be unable to remove it from their server list. If set to false, users must add the server by its server ID with the Add Server button and dialog in the Servers menu.

      • The “serverName” property defaults to “Server <server ID>” if your tenant registered the server and defaults to the same name as in the owning tenant if the server was shared with your tenant by another tenant (see the “Tooling invite flow” section below for more details). We highly recommend changing the server name before enabling or broadcasting the server.

  4. Now that you know the current properties of the server, go to the first cell under the tooling/edit_server_info heading, change the placeholder “YourServerID” to the server ID of the server you are configuring, change the other placeholder property values in the cell as desired, and run the cell.

  5. Go back to the tooling/fetch_server_info cell and run it to observe the property values of the server have changed.

Tooling steps to set and unset passcodes for servers

Important Note: Passcodes are not passwords, since they are not unique to each user. They are instead unique to each server (or at least should be!). They are viewable to admins and shared by users. For example, a classroom could use a passcode to ensure only that class can get into the server, so long as the passcode is only known to the people in the class.

  1. The second cell under the tooling/edit_server_info heading allows you to set a passcode that will be required to join the server.

  2. The third cell under the tooling/edit_server_info heading allows you to remove a passcode that you have previously set.

Tooling server deletion

  1. Before deleting a server registration, it is highly recommended that you double check the properties of the server to ensure it is the server you intend to delete. You can do so by using the tooling/fetch_server_info cell (see the “Tooling basic usage” section above for more details).
  2. Also, before deleting a registration, which is irreversible, consider disabling the server instead if you intend to restore the server to usability later. You can do so by setting the “Enabled” field to False in the first cell under the tooling/edit_server_info heading (see the “Tooling basic usage” section above for more details).

  3. If, after double checking the server is the one you want to remove and considering disabling the server instead, you determine to delete a server registration completely, you can do so by going to the tooling/delete_server_registration cell, changing the “YourServerID” placeholder value to the server ID of the server you want to delete, and running the cell.

    • If the call fails, you may have already deleted the server registration, or your tenant may not own the server. You can check by using the tooling/fetch_server_info cell (see the “Tooling basic usage” section above for more details).
    • If your tenant does not own the server, that means your tenant is a guest of the server and accepted an invite to the server. In this case, you can remove your guest registration by using the second cell under the tooling/remove_server_connection heading instead (see the “Tooling invite flow” section below for more details).

Tooling invite flow (Setting up a Server for Cross-tenant Play)

For users from two or more different tenants to join the same server, tenant admins from all tenants must work together to configure the server so users from each admin’s tenant can connect. The general outline of the flow goes like this:

  1. All participating tenants must enable Dedicated Server and Cross-Tenant Play in their tenant settings.
  2. An admin from the hosting tenant must set up the server as previously described in the “Dedicated server setup and sign in” section.
  3. An admin from the hosting tenant must invite all the other tenants to the server.
  4. An admin from each invited tenant must accept the invite to the server.

In more detail, these are the exact steps:

  1. An admin from each tenant must ensure that their tenant allows cross-tenant servers to participate.
    • The first way to enable cross-tenant servers is to enable the “Allow Cross-Tenant Servers” option on the Dedicated Server Admin Web Portal.
    • The second way is to set the equivalent “CrossTenantAllowed” property to True via the first cell under the tooling/edit_tenant_settings heading in the sample tooling notebook (see the “Tooling setup and sign in” and "Tooling tenant settings" sections above for more details).
  2. An admin from the hosting tenant must set up the server as previously described in the “Dedicated server setup and sign in” section.
    • The “CrossTenantAllowed” property must be set to True, or else sending invites, accepting invites, and users from other tenants joining the server will fail.
    • Using an allow list and/or a passcode is much more important if allowing users from other tenants so that only the users you are expecting can join. Consider configuring one or both methods of access control.
    • To set a passcode, see the “Tooling steps to set and unset passcodes for servers” section above.
    • If “allow-list” is set to true in the server's "server.properties" file, the server's “allowlist.json” file will need to be edited to include the details of any users expected to join (see the “Dedicated server allow list configuration” section above for more details).
  3. An admin from the hosting tenant must invite all the other tenants to the server.

    • Go to the tooling/create_server_invite cell, change the placeholder “YourServerID” to the server ID of the server you are configuring, replace the placeholder “…-SomeTenantID” value with the tenant IDs of each tenant to invite, make sure each tenant ID is surrounded by quotes, ensure each quoted tenant ID is separated by a comma, and run the cell.

    • If you receive the “TypeError: string indices must be integers, not 'str'” error, you need to run the first cell in the notebook to sign in again (see the “Tooling setup and sign in” section above for more details).
    • If you receive the “tooling/create_server_invite: 400 Cross-tenant is not enabled for this server.” error, you need to use the first cell under the tooling/edit_server_info heading to set the “CrossTenantAllowed” property to True (see the “Tooling basic usage” section above for more details).

    • Successfully sending the invite(s) to guest tenant(s) will result in a 200 code and the server ID showing up in a list following the tenant ID of the recipient(s).

  4. An admin from each invited tenant must accept the invite to the server.

    • Go to the tooling/accept_server_invite cell, change the placeholder “SomeServerID” to the server ID of the host tenant, and run the cell.

    • The admin of the host tenant may have communicated the server ID to the admins of the invited tenants, but if not, “ServerInvitesReceived” is a field in the result of calls to tooling/fetch_tenant_settings.

Reference A: Device code browser sign in

  1. On the website that opens, enter the code from the output and sign in as a global admin of your tenant.

  2. Once you sign in, select “Continue” when asked to confirm you are trying to sign in to “Minecraft Education Admin Tools”.

  3. When told the sign in is complete, you may close the browser tab.

Reference B: Join a server hosted by another tenant

For tenants who are not looking to create and manage servers themselves, but want to join another tenant’s server, here is a step-by-step guide for what you need to do:

  1. Enable Dedicated Server and Cross-Tenant Play in your tenant settings. You can enable both in the Dedicated Server Admin Web Portal.

  2. Send your tenant ID to the admin of the tenant hosting the server. You can find your tenant ID in the Dedicated Server Admin Web Portal.

  3. Download and install Visual Studio Code (Mac, Linux, Windows) and the Sample tooling Python notebook on your admin machine (see the “Tooling setup and sign in” section for more details).
  4. Wait for the host tenant to send out server invites.
  5. Accept the invite to the server through the sample tooling.

    • Go to the tooling/accept_server_invite cell, change the placeholder “SomeServerID” value to the server ID from the host tenant, and run the cell.

    • If you get the "401 Unauthorized" error, you need to run the first cell again, because your access token has expired (see the “Tooling setup and sign in” section for more details).

    • The admin of the host tenant may have communicated the server ID to you, but if not, “ServerInvitesReceived” is a field in the result of calls to tooling/fetch_tenant_settings. You can use that cell to check for IDs of any servers to which your tenant has received an invite

Was this article helpful?
12 out of 17 found this helpful
Have more questions? Submit a request

Related articles