Install the agent plugin

The agent plugin is the recommended way to connect a server. It streams warnings, errors, crash reports and health metrics to MCTotem, and it is the half that executes actions if you enable them later.

Requirements

• Paper or Spigot 1.19 or newer
• Java 17 or newer
• Outbound HTTPS access to mctotem.app (no inbound ports are opened)

Forge, Fabric, NeoForge, vanilla and Bedrock are not supported. The compatibility page is the full list.

Install

1. Download the agent jar and drop it into your server's plugins/ folder, then restart. That link always serves the current version; your server's setup page shows which version that is, and checksums are published for every release.
2. In the dashboard, your server shows a claim token. It is shown once; use New claim token if you lose it.
3. Paste the token into plugins/MCTotemAgent/config.yml:

claim-token: "PASTE_TOKEN_HERE"

4. Restart once more. The plugin logs "Paired with MCTotem", swaps the claim token for its own credential, and the dashboard flips to online.

Re-adding a server that was paired before works the same way: set the new claim token and restart. A claim token in the config always wins over a stored credential (agent 0.1.2 and newer).

Keeping it current

The dashboard tells you when your agent is behind, on the server page and during setup, with a download link. Replace the jar in plugins/ and restart; the existing pairing carries over and no new claim token is needed. Newer agents are not cosmetic: 0.1.3 added the join-address port cross-check, and 0.1.4 reads the commands your plugins declare so the test player knows what it can run.

The full list of config keys, including player-name redaction, is in the agent config reference.

If pairing fails: the claim token was probably already used or regenerated. Get a fresh one with New claim token in the dashboard, paste it, and restart. If the server stays on "waiting for agent", check the server console for MCTotem lines and make sure the machine can reach mctotem.app over HTTPS. More cases are covered in troubleshooting.

What the agent sends

Warnings and errors from the log (never the full INFO firehose), crash reports, TPS, memory and player-count metrics every 60 seconds, and your plugin list. IP addresses and player names are removed on your server before anything is transmitted. Outbound connections only. The exact inventory is in what data the agent transmits.

Related

• Agent config.yml keys
• What data the agent transmits
• Troubleshooting