Troubleshooting

Troubleshooting

Start with get_status. If that call fails, the problem is between the MCP server and the game; if it works, the problem is with one tool.

Symptom	Cause and fix
Could not reach the mcpfabric bridge at ...	The game is not running, no world is loaded yet, or the URL or port is wrong. The bridge starts with the game: look for [mcpfabric] ready in the log, check port in the config and MCPFABRIC_URL in the client config.
The same message with timed out after ...ms	The game is paused or frozen, or the call is slow. Raise MCPFABRIC_TIMEOUT_MS (MCP side) or callTimeoutMs (mod config).
Authentication error (401)	MCPFABRIC_TOKEN is missing or does not match token in config/mcpfabric.config.json. Copy it again; each Minecraft instance has its own.
403	The request had an Origin header. The bridge refuses browsers on purpose. Use the MCP server, not a web page.
415 Content-Type must be application/json	A hand-written request without the JSON content type. Add Content-Type: application/json.
unavailable, message names enable...=false	That capability group is switched off in mcpfabric.config.json. Turn the flag on if you want it, then restart the game.
A client tool needs the client (or a server tool needs a server)	control, interact, vision, navigation, player and inventory exist only on the client. World, entity, player admin and command tools need a server (integrated or dedicated). get_status shows the side.
At most 16 event streams may be open at once	Too many open /events streams. Close old clients.
Port 25599 is busy	Another game instance or a leftover process uses it. Change port in the config of one of them.
The MCP server crashes at start	Node.js older than 22.16. The agent runtime needs node:sqlite; check node --version.
The agent forgets everything	Memory is per world, in ~/.mcpfabric/agent.db. A different world id, MCPFABRIC_DATA_DIR, or MCPFABRIC_AGENT=off changes that.
A job stops with a health reason	It stops when health drops to the limit (6 by default) so the model can decide what to do. Eat, heal, start it again.
Build fails with Remote host terminated the handshake	A TLS-inspecting antivirus or firewall while downloading dependencies. Re-run the build; the download cache persists.
Build fails on the wrong JDK	1.21.x needs JDK 21, the 26.x line JDK 25. chiseledBuild runs Gradle on JDK 25 with JDK 21 installed.

Still stuck? Open a setup help issue with your Minecraft version, loader, mod version and the log lines starting with [mcpfabric]. Never paste your token.