Plugin

Talk to your agents
in game

MCAgentsChat is where a conversation happens. One command opens it, your chat messages carry it, and the agent answers with every tool MCAgents has been given — while you keep talking as yourself.

View on GitHub Release notes
PaperMC SpigotMC FoliaMC
MCAgentsChat requires MCAgents. MCAgents is the core provider — it holds the API keys, the models, and the tools — and this plugin is the way a player reaches it. Installed on its own it disables itself at startup and says so in the log.

How a conversation works

Four steps from a chat message to an answer, and nothing in between belongs to this plugin.

  1. You open a session

    /chat starts a conversation the agent remembers; /chat ask starts one where every message is answered on its own. Either way, your ordinary chat messages become the conversation until you type quit or exit.

  2. Your message is claimed, not broadcast

    While a session is open your messages go to the agent instead of to public chat, so a conversation never leaks into the server chat around you. The console works the same way: every line typed there goes to the agent until the session ends.

  3. MCAgents answers it

    The message is handed to MCAgents with the conversation so far. It resolves the model and the key, runs the staged tool workflow, and returns the reply — so an agent you talk to here can call every tool any plugin has registered there.

  4. The transcript is filed when you leave

    A conversation lives in memory while it runs and is written to MCAgents' own chat log when the session ends. This plugin has no database of its own and stores nothing on disk.

Two ways to talk

Both modes can call tools. The difference is whether the agent remembers what you already said.

Chat mode

The prior turns travel with every message, so "keep going" and "do that again for the other one" mean something. Best for working through a problem.

Ask mode

Each message is answered on its own with no memory of the last. Best for a string of unrelated questions, and cheaper, because nothing is replayed.

Saved prompts

Run a prompt you saved earlier by id. Players run their own; the console runs the server's. When the entry names tools, the agent is limited to exactly those.

One request at a time

A player waits for their answer before sending again, so nobody can queue up a dozen requests — and a dozen charges — at once. A hung request releases itself after a countdown.

Whose key pays for it

MCAgentsChat holds no API key. Every request is billed by MCAgents to whoever is talking, decided by what kind of caller they are rather than by what permissions they hold.

A player spends their own

Your conversation runs on the OpenRouter key you registered with MCAgents. An operator is still a player here: holding a permission node does not start spending the server's key.

The console spends the server's

A conversation started at the console runs as the server, on the key the server configured. So does every automated test run, whoever typed the command.

Nothing to configure here

Keys and models are set with MCAgents' own command. This plugin's configuration is two settings: whether it is on, and how long a request may stay pending.

Testing the agents

Operators can exercise the whole agent workflow without playing through it by hand. /chat tester replays saved prompts and grades the results, so commands, workflow logic, and tools stay reliable as the ecosystem grows.

A shared test registry

Tests live in one file, grouped by plugin, so MCAgents 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 run as the server

A test run is the server's own work, so it spends the server's key whoever started 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.

It binds to MCAgents at runtime

MCAgentsChat is not built against MCAgents. It finds it on the running server and binds to it there, which is what lets one build of this plugin work beside more than one build of that one.

Found, not compiled in

At startup the plugin looks for MCAgents and for everything it needs from it. A version mismatch becomes a clear line in the log instead of a crash halfway through answering somebody.

Missing means off, not broken

Without MCAgents there is nothing to chat with, so the plugin disables itself rather than leaving a command that cannot answer. The rest of your server is untouched.

Room for more

Each integration lives on its own, so a future binding to another plugin is added beside this one without disturbing it.

Who may do what

Every /chat subcommand carries its own permission node under the mcpaimon.mcagentschat. prefix, so access is set per command rather than by operator status alone.

Open to players by default

Both conversation modes and running a saved prompt are allowed out of the box, because a message spends the player's own key.

Operators by default

Reloading the registries and running the test suite are restricted, because they touch shared state and spend the server's key.

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.

This site explains how the ecosystem works. Setup guides, the full configuration reference, and source code live in the mcagents-chat repository.