Bring into your
Minecraft server
MCAgents is the MCPaimon main plugin. It lets players and operators talk to AI agents in game, and it gives those agents safe, permission-aware tools to read and manage the server.
How it works
The plugin sits between your players and the AI platform of your choice. Every conversation flows through the same five stages.
-
A player talks to the agent
Players use the
/aicommand (alias/mcagents) to ask one-off questions, or switch into a dedicated chat mode where every message goes straight to the agent. -
The plugin resolves the session
Each player has an active session: the AI platform and model they selected, plus the token that authorizes them. Operators register platforms and models once; players pick from them.
-
The agent thinks and calls tools
The agent answers in natural language, and when it needs live information or wants to act, it calls the plugin's built-in tools or the tools that extensions have registered — always inside the permission rules of the tool.
-
Tools respect Minecraft permissions
Every tool checks who is asking. Regular players can only query themselves, while operator-only tools verify OP status in code before doing anything.
-
Everything is stored centrally
Platforms, models, accounts, sessions, saved player prompts, and conversation logs can live on the central API server, so a whole network of Minecraft servers shares one consistent store.
The central API server
MCAgents can keep its data in a local database, or delegate storage to the central Express.js server that powers the wider MCEngine/MCPaimon ecosystem.
One route for the plugin
The plugin speaks to the central server through the /api/mcagents route, which stores AI platforms, models, accounts, active sessions, player prompts, and logs.
Token-protected
Every request carries a Bearer token, and the server enforces rate limits, so only trusted game servers can read or write agent data.
Shared across servers
Because storage is centralized, players keep their platforms, sessions, and history when they hop between the Minecraft servers of a network.
Extensions
The essentials ship inside the plugin itself: the /ai command,
the chat listener, token management tools, and dynamic custom tool loading.
Extensions build on that core — they only add tools, commands, and listeners
to MCAgents and never need their own route on the central server. All
extensions run on PaperMC, SpigotMC, and FoliaMC.
PlayerTools
Player information and administration: identity, health, food, bans, IP checks, and operator audits — all permission-aware.
How PlayerTools works →ServerTools
Server health at a glance: tick rate, player latency, address details, and the installed plugin list for operators.
How ServerTools works →Template
A ready-made boilerplate for building your own extension, mirroring the structure used by every official extension.
Repository ↗Everyday commands
Everything is reachable from a single command, explained here in plain words.
Ask
Send the agent one question and get one answer — no mode switching, no setup beyond an active session.
Chat mode
Toggle a personal conversation mode where your chat messages go to the agent until you leave the session.
Active platform & model
Choose which registered AI platform and which of its models your session should use.
Tokens
Store, change, inspect, or remove the API token that authorizes you on a platform. Creating new platforms and models is reserved for operators.
Saved prompts
Ask the agent to save a prompt once, then run it again by id whenever you like. Every player keeps their own prompts with their account, while the server's prompt file belongs to the console alone.