Numen MCP

Turn your Numen companions into tools an external AI can drive. Numen MCP runs a small Model Context Protocol server inside your game client, so an agent like Claude can list your companions, take control of one, and call its tools directly — Claude becomes the brain, the companion is its hands and eyes.

Multi-loader (Fabric + NeoForge), Minecraft 1.21.1.

⚠️ This mod does nothing on its own. It requires Numen (the companion engine) and an external MCP client (e.g. Claude Code / Claude Desktop) to connect to it. See Requirements below.

How it differs from a normal Numen companion

A Numen companion normally thinks with its own built-in LLM. Numen MCP lets an outside brain skip that LLM entirely:

Claude is the player. It reads the world through perception tools (get_self_status, scan_blocks, …) and decides every action itself.
No Numen API key needed for this mode — Claude does the reasoning; the companion just executes tools.
Parallel fleets. Every call is addressed to one companion, so one agent can drive several companions at once.
Survival-legitimate. The exposed tools are the same ones the built-in brain uses — mine, move, place, craft. Nothing conjures items from nothing.

Requirements

Numen 0.0.4+ — the companion engine (bundles the numen-api runtime this mod drives).
Client-side. Companions and their tools live in the owner's game client, so install it there.
An MCP client — Claude Code (native HTTP) or Claude Desktop (via mcp-remote).

Setup

Install Numen + Numen MCP in your client. Launch once; it writes config/numen/mcp_server.json and prints MCP server up on http://127.0.0.1:8765/mcp when listening.

Point your MCP client at it:

Claude Code — .mcp.json in your project:

{ "mcpServers": { "numen": { "type": "http", "url": "" rel="noopener nofollow" target="_blank">http://127.0.0.1:8765/mcp&quot; } } }

Claude Desktop — claude_desktop_config.json (needs Node/npx):

{ "mcpServers": { "numen": { "command": "npx", "args": ["mcp-remote", "http://127.0.0.1:8765/mcp"] } } }

Summon a companion in-game, then in your agent: list_companions → acquire_companion → drive it. The server only listens while the game is running.

Tools

Tool	What it does
`list_companions`	List your live companions (name + id)
`acquire_companion`	Take control — pauses the built-in brain, frees the body
`release_companion`	Hand the companion back to its built-in brain
(engine tools)	Every Numen body/perception tool (`get_self_status`, `scan_blocks`, `auto_mine`, `move_to`, `place_block`, …), each taking a `companion` argument

On connect, the server hands the agent a short briefing (MCP's instructions) — what Numen is and the acquire → perceive → act → release loop — so any MCP client works out of the box.

Multiplayer

Works on remote servers. Numen MCP is client-only and drives through Numen's existing client→server protocol — the same packets the built-in brain uses. The server needs Numen installed (as it already does for companions to exist); it does not need Numen MCP. The server owner-checks every action, so you can only drive companions you own.

Networking & privacy

Numen MCP opens a local, loopback-only HTTP endpoint (127.0.0.1:8765 by default) for your MCP client to connect to. Nothing is exposed to the internet, and no data leaves your machine. It's fully configurable in config/numen/mcp_server.json:

enabled — master switch.
host / port — bind address (loopback by default).
token — optional bearer token required on every request.
call_timeout_seconds — how long a tool call waits before timing out.
hidden_tools — engine tools not exposed to the external agent.