The MCP endpoint for driving Minecraft bots. Speaks Streamable HTTP to agents on one side and the
bot protocol to bots on the other.
It does not know how to play Minecraft. A bot does that, and there are two kinds:
bot-fabric, a real Minecraft client that renders, so
it can take a screenshot and press a dialog button, and follows the game rather than
reimplementing it; and , a headless client
in a few megabytes that joins in under a second, for many bots at once or a fast loop. A bot
announces its kind when it links, shows it, and a tool no bot of that kind can run is
refused by name before anything is sent. The says which tools the
headless kind does not run; the arrangement is documented in .
Local development only. Bots authenticate offline, so the target server has to run
offline-mode.
What this is for
Driving a Minecraft client from an agent, for two jobs. Running the QA a person used to do by
opening the game and looking, and closing the loop while developing — build, deploy, have the
agent press the thing, find the edge case.
That purpose settles the design arguments. When a choice comes up, it is decided by whether the
answer tells you what went wrong when something fails, and whether it keeps the build-and-check
loop short. Not by how many tools it adds.
The catalogue as a page: every tool by group, its arguments, what it answers with. Rendered by ./gradlew renderToolReference, and the build fails when it is stale
The catalogue is the single source. tools/list is built from it, argument validation runs
against it, a bot's argsHash is checked against it at handshake, and the tool reference is
rendered from it.
Leaving MCP_AUTH_TOKEN unset leaves /mcp open and says so in the log. That is the right
default for a laptop and the wrong one anywhere a pod can reach it, so the chart sets one.
/actuator is never behind the token: a probe cannot carry one.
Where it listens follows from the token. MCP_BIND_HOST overrides; without it the server binds
127.0.0.1 when MCP_AUTH_TOKEN is blank and 0.0.0.0 otherwise, because a server with no
token is a laptop's and one with a token is a pod's. The chart and the operator set 0.0.0.0
explicitly all the same. On /mcp a request with no Origin header passes, which is what Claude
Code and most clients outside a browser send; an Origin of localhost or 127.0.0.1 on any
port passes; MCP_ALLOWED_ORIGINS (a comma-separated list) extends that. The Host header is
not checked.
Everything else the server reads from its environment, with what it means and what it does when
unset:
variable
meaning
default
MCP_AUTH_TOKEN
The bearer token /mcp and /regions require. Blank leaves them open
How often a bot re-sends an action bar, title or dialog that is still showing; a run nothing has repeated for three of these is closed
1000
BOT_LINK_MUTED_FEEDS
Feeds bots are told not to push, comma separated: chat, actionBar, title, dialog, effect, toast. effect is the one a busy server floods
none
BOT_LINK_TOKEN
What a bot's hello has to carry; one without an equal linkToken is refused. Blank takes any bot that dials in
blank
MCP_MAX_BOTS
How many bots may be linked at once. A bot turned away is told this number
16
MCP_BOTS_PROVISION
Whether join-server creates a MinecraftBot for a name nothing runs under: auto looks for a cluster only from inside one, always uses whatever kubeconfig is around, never does not look
auto
MCP_BOTS_NAMESPACE
Where those bots are created
the pod's own namespace
MCP_BOTS_MCP_HOST
What a created bot is told to dial
the chart's Service in that namespace
MCP_BOTS_PROFILE_KIND, MCP_BOTS_PROFILE_NAME
The MinecraftBotProfile (or ClusterMinecraftBotProfile, by kind) every bot started here is built from
the operator's: the namespace's default, then the cluster's
MCP_BOTS_LINK_SECRET
The Secret (key token) in that namespace a bot started here reads its BOT_LINK_TOKEN from, written as spec.linkTokenSecretRef. Blank declares bots without one
blank
MCP_LOG_LEVEL
Log level for kr.junhyung.mcagents
INFO
The image comes from Paketo buildpacks, not a Dockerfile:
./gradlew bootBuildImage
The JVM's heap is then sized from the container's real limit rather than a percentage someone
guessed, and an SBOM comes with it. One invocation builds one architecture; CI runs it on a
native runner per architecture and joins the two into a manifest list.
Agents connect to /mcp; bots dial in on :8765. Every tool in the catalogue is in tools/list before any
bot has linked, because an MCP client reads that list once when its session opens.
/regions is the one thing beside /mcp behind the token. A box read-region reads is kept in
memory under an id, and GET /regions/<id>.schem downloads it as a Sponge schematic while
POST /regions (the file as the body, ?name= optional) keeps one and answers with its id, which
write-region then puts down. The store holds sixteen million blocks and lets the oldest go; a
restart empties it. A file is the shape a region takes between servers, or between a person's
WorldEdit and an agent, and a tool call is the wrong size for it either way.
dev/ has a fake bot that speaks the whole protocol, a sweep that calls every
tool, and a one-liner for calling one by hand. None of them needs a Minecraft client.
A wrong or missing token is answered 401 with WWW-Authenticate: Bearer, so a client that
cannot connect has that to look for. Against the development cluster, make -C dev/cluster names
prints this line with the cluster's own token in it.
Three ways to run it
Which one depends on what is around, and they do not stack: each is a whole deployment.
A cluster, one server. The chart installs the Deployment, the Service's two ports and the tokens; bots come from the operator, and join-server asks it for one.
A cluster with tenants. A namespace gets a server by creating one CR, and the operator renders the same objects the chart does, plus the bot pods, plus autoscaling.
No cluster. This server, a scalable headless bot and one fabric bot on one machine.
The two cluster paths are not layered: an MCPServer does not install the chart, it builds the
same thing from Go. The chart is here because one server does not need an operator, three CRDs and
a cluster-wide RBAC in front of it.
Keep both. The chart generates neither, and will not render without auth.token or
auth.existingSecret: a token that differs on every render leaves a GitOps application
permanently out of sync, which is worse than an install that stops and says so. The same goes for
replicaCount > 1, which fails rather than installing a second pod that would answer about bots
it cannot reach, and for bots created in another namespace than the link Secret they are pointed
at. The chart's README has the rest: what the two tokens
gate, when existingSecret means a rotation no longer rolls the pod, and why bots.namespace is
worth setting.
In Docker, without a cluster
deploy/compose/ is this server and some bots in docker compose, for a
Minecraft server you already run:
make -C deploy/compose up # both tokens into .env on the first run, the lot, then the line above
make -C deploy/compose names # that line again later, whenever you want the token back
The Minecraft server is not in that project. A bot is told where one is by join-server, and
host.docker.internal reaches a server on the same machine, which is also how a forwarded port
works. Bots authenticate offline there by default, which is what makes --scale bot=4 mean
anything: replicas share every environment variable, so a bot left without a BOT_NAME takes its
container id for a name and four of them are four bots. Microsoft accounts are the opt-in, for a
server whose online-mode stays on — one account per bot, written out by hand, and the login is a
one-shot (docker compose run --rm bot-login) rather than something a long-running bot does, since
a bot waiting on a prompt nobody is attached to looks exactly like a bot that cannot connect.
It does generate both tokens, where the chart refuses to: nothing renders a file on one machine
twice, so the reason the chart has for not doing it does not apply. What compose does not have is
the operator — no autoscaling, nothing probing liveness to restart a wedged server, no profile
pinning — and the image tags are literals in compose.yml rather than a profile.
End to end
./gradlew :e2e:test
e2e/ is a project of its own: it starts the jar a release ships, a Paper server with the
fixture datapack in it and a real bot in a container, and then asks the MCP endpoint for things and
asserts the sentence that comes back. It compiles against nothing in this project, so what it holds
is the contract rather than the code behind it.
Every case in it is a bug that was once shipped. What found those was a set of scripts somebody had
to run and read; none of them could fail a build, so a renderer that started saying something else
went unnoticed until the next time anyone looked. The assertions are against the expected sentence
rather than against a second bot, because two implementations agreeing is a weaker thing to know --
they agreed for a while that a chat line reading "Hello world" was "Hello | world".
It needs Docker and a bot image, so it is not part of build. Which bot to drive is the build's to
say; the Minecraft version follows the kind, 26.3 for fabric and 26.1.2 for azalea, which has no
release past it:
./gradlew :e2e:test -Pe2e.bot.image=<image>
CI shares a fabric bot's cases out between four runners, each with a server and a bot of its own,
and a failure names the shard it happened in. The same share runs locally with -Pe2e.shard=2/4.
The Paper server, and Testcontainers' own ryuk and sshd, are Docker Hub images. Locally they are
pulled from there with no login. In CI they come through the registry's private proxy cache, which
is what -Pe2e.hub.prefix=junhyung.cloud/docker-hub/ (or E2E_HUB_PREFIX) puts in front of the
Paper image's name and TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX puts in front of the other two;
both are empty by default. The bot images are on the public mc-agents project either way.
Releases
A push to main publishes the image and the chart, once every job before it is green: the unit
tests and the tool sweep, the two architectures' images, and every end-to-end shard. A red shard
blocks the tags, the chart and the release rather than shipping beside them; there is no branch
ruleset, and this gate is what stands between a red suite and a release. A push that changes
nothing the image or the chart is built from publishes nothing.
The stamped tag, <version>-<utc stamp>.g<sha>, is immutable; :<version> and :latest move to
the newest build of that version, so a deployment that must not change pins the stamped tag or the
digest. The same push tags the commit v<version> and makes a GitHub Release whose notes are the
commits since the previous tag, followed by the catalogue version and the bot tags the suite ran
against (the ones dev/cluster/mcpserver.yaml pins);
hack/release-notes.sh writes them, and runs locally.
Which release of each repository goes with which is the operator's to say, since the operator is
what installs the set: the table is
operator/docs/compatibility.md,
one row per operator release, with the order the pieces are released in.
Status
The server answers the whole catalogue. join-server sends a bot that has linked into a world, and
in a cluster it starts one first when none is running under that name, by creating a
MinecraftBot for the operator to run.
In a cluster, run this server through the operator: an MCPServer in the namespace that uses the
bots gets a server, its token and the RBAC to create bots there, and nowhere else. The chart in
charts/ is for running the server without the operator managing
it; creating bots still needs the operator's CRDs.
Known limits
The bot port has two gates, and both are off by default. The first is a NetworkPolicy:
networkPolicy.enabled in the chart, or one the operator's user adds. The chart's opens :8765
to the bot pods alone, /mcp to the agent pods, and its third rule opens the MCP port to the
namespaces in networkPolicy.metricsFrom for scraping, and to nothing else; kubelet probes need
no rule. The second is the link token, botLink.token or botLink.existingSecret in the chart
(BOT_LINK_TOKEN on the server): a bot's hello has to carry it or the bot is refused, so a pod
that gets past the policy still cannot introduce itself as a bot. Bots the server starts are
pointed at the same Secret; one declared by hand needs spec.linkTokenSecretRef. The operator
sets both up for an MCPServer. With neither, any pod that can reach the port is a bot.
The token carries no identity. Every agent presents the same bearer token, so the server cannot
say who asked for a bot; join-server's owner is the only audit trail, and it is whatever the
caller wrote.
Cancelling a call does not stop the bot. The MCP SDK gives a tool handler no cancellation hook,
though the bot protocol has cancel. An abandoned move-to-position keeps walking to its deadline,
and the bot refuses another exclusive tool until then (RemoteTools.claim). When the SDK exposes
one: complete the pending BotLink call with Messages.Cancel and release the claim.
One replica. Bots are a shared resource, and sharing them across replicas needs leases and a
roster. The requirement that replicas scale is about bot pods, which do scale, so that complexity
is not paid for here.
Licensed under the Apache License 2.0; see LICENSE.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Mc Agents?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Mc Agents necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Mc Agents?
Mc Agents se ejecuta localmente por stdio.
¿Cuándo se comprobó Mc Agents por última vez?
Última comprobación: 2026-11-11. model context protocol server
