| name | setup-mcp-server |
| description | Step 3 of 4 of the Minecraft Bedrock MCP setup. Install the minecraft-bedrock-mcp-server, generate its bearer tokens, write its .env, configure the behavior pack's permissions/variables/secrets files, start BDS and the MCP server, and verify the bridge handshake. Use when the user has a Bedrock server and a world with the behavior pack installed and needs the MCP server running. |
Install and run the MCP server (Step 3 of 4)
This is Phase 3 of the four-phase Minecraft Bedrock MCP setup. It assumes
Phase 2 (setup-minecraft-world) is done. You should have, written down:
- the world path, e.g.
/opt/bedrock-server/worlds/mcp-world
- the behavior-pack path, e.g.
<world>/behavior_packs/bedrock-bridge
If either is missing, get it before continuing. The MCP server runs on the
same host as BDS and needs Node.js 20+ there — verify with node -v.
How the pieces talk
The MCP server exposes two authenticated surfaces:
/mcp — what Claude connects to (Phase 4), guarded by BRIDGE_CLIENT_TOKEN./bridge — what the behavior pack long-polls, guarded by BRIDGE_AGENT_TOKEN.
So there are two separate tokens. Keep them straight: the client token is
for Claude, the agent token is for the behavior pack inside the world.
Step 1 — Install the MCP server
On the BDS host:
npm install -g minecraft-bedrock-mcp-server
Alternatives, if the user prefers: npx minecraft-bedrock-mcp-server (no
install), or the Docker image
ghcr.io/chapmanjw/minecraft-bedrock-mcp-server:latest (docker run --env-file .env -p 8765:8765 ...). Pin to a version tag for reproducibility, and keep it
aligned with the BDS and behavior-pack versions.
Step 2 — Generate the two tokens
Generate two long random secrets:
openssl rand -hex 32
openssl rand -hex 32
On Windows without openssl:
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
Have the user keep both values somewhere safe. They are needed again in this
phase and in Phase 4.
Step 3 — Write the MCP server .env
Create a .env file for the MCP server (this plugin ships .mcp.json.example
in its repo root as a reference, but the server's own .env is what matters
here):
BRIDGE_CLIENT_TOKEN=<first secret>
BRIDGE_AGENT_TOKEN=<second secret>
BRIDGE_WORLD_PATH=<the world path from Phase 2>
BRIDGE_BEHAVIOR_PACK_PATH=<the behavior-pack path from Phase 2>
BRIDGE_HOST=0.0.0.0
BRIDGE_PORT=8765
Other variables (BRIDGE_TLS_CERT/BRIDGE_TLS_KEY, BRIDGE_TRUST_PROXY,
rate limits, etc.) have defaults; leave them unless the user has a reason. The
full reference is in the
MCP server README.
TLS: the bridge carries bearer tokens and world data. On anything beyond
a fully trusted LAN, set BRIDGE_TLS_CERT/BRIDGE_TLS_KEY or terminate TLS
at a reverse proxy. For a first local setup, plain HTTP is acceptable — note
the server logs a warning when running without TLS.
Step 4 — Configure the behavior pack
The pack reads config from the BDS scripting config directory:
<bds>/config/default/. Create that folder and add three files. The
behavior pack repo ships copy-ready versions under its config/default/.
permissions.json — lets the pack load its Script API modules:
{
"allowed_modules": ["@minecraft/server", "@minecraft/server-net", "@minecraft/server-admin"]
}
variables.json — where the bridge listens. This is the MCP server's
/bridge surface. If the pack and server are on the same host, localhost is
right:
{ "bridge_url": "http://localhost:8765" }
secrets.json — the bridge token. The value is the full Authorization
header: the literal word Bearer, a space, then the BRIDGE_AGENT_TOKEN
(the second secret):
{ "bridge_agent_token": "Bearer <the BRIDGE_AGENT_TOKEN second secret>" }
The Bearer prefix must be inside the stored secret. The pack receives
an opaque secret handle it cannot read or concatenate, so the scheme prefix
has to travel as part of the secret value itself. This is the single most
common setup mistake — double-check it.
Never commit secrets.json anywhere.
Step 5 — Start everything
Start the MCP server first, so the bridge is listening when the world
loads, then BDS.
Option A — foreground (quick test)
minecraft-bedrock-mcp-server
cd /opt/bedrock-server && LD_LIBRARY_PATH=. ./bedrock_server
On Windows: run minecraft-bedrock-mcp-server in one terminal (with .env in
the working directory) and bedrock_server.exe in another.
Option B — long-lived service (recommended)
For a deployment that survives logout and restarts, install both as services.
On Linux, use systemd — the
MCP server README, Step 7
has ready-to-paste bedrock-server.service and mc-mcp-server.service units,
a dedicated minecraft user, and a locked-down EnvironmentFile. On
Windows, wrap each executable as a service with NSSM or a Task Scheduler
"at startup" task. In all cases, start the MCP server before BDS.
Walk the user through whichever they choose; don't paste the full systemd
units unless they pick Option B on Linux — then reproduce them from the README.
Step 6 — Verify the handshake
When the world loads, the behavior pack handshakes with the bridge. Check:
- Liveness:
curl http://localhost:8765/healthz returns OK.
- MCP server log: shows a successful bridge handshake.
- BDS log: shows the
bedrock-bridge pack's script starting.
If the handshake fails, the usual causes, in order of likelihood:
- Token mismatch —
bridge_agent_token in secrets.json ≠ Bearer +
BRIDGE_AGENT_TOKEN in .env. Check the Bearer prefix and for stray
whitespace.
- Wrong
bridge_url in variables.json, or the MCP server isn't running
/ isn't reachable on that host:port.
- Behavior pack not active —
world_behavior_packs.json missing or wrong
UUID, or the world wasn't created with Beta APIs.
config/default/ in the wrong place — it must be under the BDS root,
not the world folder.
Wrap up
Confirm with the user:
Hand off: Phase 3 is done — the world is now reachable over MCP. The last step
is connecting Claude to it. Offer to continue with the connect-claude
skill now. The user will need the BRIDGE_CLIENT_TOKEN (the first
secret) and the server's host:port for that step.
