The your
Minecraft server builds on
MCAgents is the MCPaimon core plugin. It gives a server one way to reach an AI provider, one registry of safe, permission-aware tools, and one place API keys live — then hands all of that to the plugins built on top of it.
A core, and the plugins on it
MCAgents does not talk to players. It is the layer everything else asks, so a server runs one AI setup no matter how many plugins use it.
MCAgentsChat
The chatting interface. One command opens a conversation with an agent, and every tool registered here is available while you talk.
How MCAgentsChat works →MCAgentsNPC
AI driven NPCs that gather, farm, fight, keep watch, and follow you, and take their instructions in plain language.
How MCAgentsNPC works →Your own plugin
Anything that registers a tool, or sends a prompt of its own, is built the same way — on this plugin's public interface, with no route of its own on the central server.
What the core does
Four jobs, shared by every plugin built on it, so none of them has to solve any of it again.
-
One connection to the AI provider
MCAgents talks to OpenRouter, and its endpoint is built in. A server picks which models it offers; a plugin asking for an answer never chooses a provider or holds a connection.
-
One rule for whose key is spent
Every request says what kind of caller it is for, and that decides which key pays: a player's own, a guild's, or the server's. A new kind of owner plugs into the same rule without changing it.
-
One registry of tools
Built-in tools, external scripts, and tools contributed by other plugins all live in one place, so an agent reached through any plugin can call all of them — inside the permission rules of each tool.
-
One staged workflow, with caching
A prompt is resolved through a funnel rather than by sending every tool definition on every call, and reused context is cached where the model supports it. Every plugin gets that economy for free.
-
One store
Models, accounts, sessions, saved 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 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 sessions and history when they hop between the Minecraft servers of a network.
Talking to an agent: MCAgentsChat
Conversation used to live inside this plugin. It is now its own one, MCAgentsChat, which asks MCAgents to answer every message. The split is why a server that never wants in-game chat does not have to install it, and why the core stays a provider.
What it does
One command opens a conversation, two modes decide whether the agent remembers it, and saved prompts run by id.
How MCAgentsChat works →It uses your key, through MCAgents
MCAgentsChat holds no key of its own. Every message is answered by MCAgents on the caller's own account, and the console's conversations run on the server's key.
Required, and it says so
Chatting needs the core, so MCAgentsChat disables itself when MCAgents is missing rather than leaving a command that cannot answer.
Extending the agent
The core ships the tools that manage the core itself: keys, models, and saved prompts. Everything beyond that is added from outside — by your own scripts, or by another plugin that registers tools of its own.
Your own scripts as tools
Point the plugin at a script and describe it in Markdown, and the agent can call it like any built-in tool — no Java, no rebuild.
Tools from another plugin
Any server plugin can register its own tools, categories, and saved prompts with MCAgents at startup, and they join the same permission-aware workflow.
Nothing extra on the server
Added tools store their data through MCAgents itself, so they never need a route of their own on the central API server.
Everyday commands
The core's own command is two settings wide. Everything a player does with an agent is a command in the plugin that owns that feature.
Your key
Register the OpenRouter key your requests spend. It is encrypted before it is stored, and it is yours alone — no plugin built on the core ever sees it.
Your model
Choose which of the server's models answers you. Skip it and your requests run on the server default.
The server's key
Set once in the configuration, and spent by anything acting for the server — the console, an administrative action, an automated test run. A player is never charged to it.
Everything else lives elsewhere
Conversations are MCAgentsChat, NPCs are MCAgentsNPC, and your own features are your own plugin. The core keeps no command for talking to an agent.
Testing the agents
Operators can exercise the whole agent workflow without playing through it by hand. The test runner lives in MCAgentsChat and replays saved prompts against the tools registered here, so workflow logic and tools stay reliable as the ecosystem grows.
Run a suite, or one test
Run every saved test for a plugin, or a single one by id. It is reserved for operators and the console because it spends a key and writes files.
A shared test registry
Tests live in one file, grouped by plugin, so the core and every plugin built on it keep their regression prompts in one place. Each test can pin the agent to a fixed set of tools or let it run the full workflow.
Always the server's key
A test run is the server's own work, so it spends the server's key whoever starts it. An operator never pays for a test suite out of their own account.
Markdown reports
Each run writes a timestamped report recording the prompt, the agent's result, and an AI-written evaluation summary, so outcomes can be reviewed and compared over time.
Who may do what
Every subcommand carries its own permission node, in the core and in each plugin built on it, so access is set per command rather than by operator status alone.
Open to players by default
Storing a key, choosing a model, and talking to an agent are allowed out of the box, because a request spends the player's own OpenRouter key.
Operators by default
Reloading shared registries and running the test suite are restricted, because they touch shared state and spend the server's own key.
Tune it per role
Any node can be granted or withheld with your usual permission manager — hand the test suite to a moderator, or keep prompt saving out of a guest world.
Hidden, not just blocked
The help menu and tab completion show only the subcommands you actually hold, so a withheld command never appears as a dead end.