# Setup Server

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-chapmanjw-minecraft-java-fabric-claude-plugin-setup-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [chapmanjw](https://agentstack.voostack.com/s/chapmanjw)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [chapmanjw](https://github.com/chapmanjw)
- **Source:** https://github.com/chapmanjw/minecraft-java-fabric-claude-plugin/tree/main/skills/setup-server
- **Website:** https://github.com/chapmanjw/minecraft-java-fabric-mcp-server

## Install

```sh
agentstack add skill-chapmanjw-minecraft-java-fabric-claude-plugin-setup-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Configure and run the MCP server (Step 3 of 4)

This is **Phase 3** of the four-phase Minecraft Java MCP setup. It assumes
Phase 2 (`setup-mod`) is done: the MCP mod jar and Fabric API jar are in
`mods/`. The MCP server is embedded in the mod, so "running the MCP server"
means launching Minecraft (single-player) or the dedicated server.

Work interactively. Branch on the choice from Phase 1: **single-player** is
mostly defaults; **dedicated/remote** needs a config file and a token.

## Where config lives

The mod reads `config/minecraft_fabric_mcp/config.json` under the game
directory:

- **Single-player:** `/config/minecraft_fabric_mcp/config.json`.
- **Dedicated server:** `/config/minecraft_fabric_mcp/config.json`.

The file is **optional** — it's only needed to override defaults. Any field can
also be overridden by an environment variable named `MCP_` (e.g.
`MCP_PORT`, `MCP_AUTH_REQUIRED`).

The defaults are deliberately safe: bind `127.0.0.1`, port `8765`, **no auth**,
reject all cross-origin browser requests.

> **There are two servers.** The above is the **world** server (`minecraft-java`,
> the `main` entrypoint). The same jar also has a **client inspection** server
> (`minecraft-java-client`, the `client` entrypoint) that runs inside a real,
> rendered Minecraft client and serves the `client` category — `view_capture` (a
> real first-person PNG) and `sense_*` / `client_status`. It reads a **separate**
> config `config/minecraft_fabric_mcp/client.json` (default port **8766**, env
> prefix **`MCP_CLIENT_*`**) and defaults to exposing only the inspection tools.
> It needs a real client window with a GPU — it is **not** part of a headless
> dedicated server. This phase configures the world server; running the
> inspection server (and the server-only / client-only / combo patterns) is
> covered in `setup-connect`. Most fields below apply to both — only the file
> name, default port, and env prefix differ.

---

## Single-player branch — defaults are enough

For Claude running on the **same machine** as Minecraft, you do **not** need a
config file. The mod listens on `http://127.0.0.1:8765/mcp` with no token.

### Step 1 — Launch

Have the user start the Fabric profile in the Minecraft Launcher and load any
world. (At least one loaded world is needed — many tools act on the world or
relative to a player.)

### Step 2 — Verify it's listening

Check the game log for:

```
[minecraft_fabric_mcp] MCP server listening at http://127.0.0.1:8765 (host=127.0.0.1, port=8765, auth=false, tls=false)
```

Then the liveness probe (no auth required for `/healthz`):

```sh
curl http://localhost:8765/healthz
# → {"status":"ok"}
```

If `/healthz` answers, Phase 3 is done — skip to **Wrap up**. There is no token
for this path.

---

## Dedicated / remote branch — config + token

Use this when Claude connects from another machine, or you want LAN/internet
access. (If Claude runs on the *same host* as the dedicated server, you can use
the single-player defaults above and skip the config file.)

### Step 1 — Write `config.json`

Create `/config/minecraft_fabric_mcp/config.json`:

```json
{
  "host": "0.0.0.0",
  "port": 8765,
  "allow_remote": true,
  "auth_required": true,
  "rate_limit_rpm": 120
}
```

Leave `bearer_token` unset — the mod generates a 256-bit token on first boot
and logs it once.

> **The mod refuses unsafe bindings.** Binding to a non-loopback host
> (`0.0.0.0` or a LAN IP) requires **both** `allow_remote: true` **and**
> `auth_required: true`. If either is missing, the mod errors at startup rather
> than exposing an unauthenticated world to the network. This is intentional —
> don't work around it.

Optional fields the user may want:

- `tls_cert_path` / `tls_key_path` — PEM cert + PKCS8 key for TLS at the mod
  (set **both** or neither). For internet-facing servers, use TLS here or
  terminate it at a reverse proxy. See the mod's `docs/security.md`.
- Tool-surface controls (`included_categories` / `excluded_categories` /
  `max_access`) — see the section below; with no config the mod registers a
  lean ~102-tool surface.
- `command_timeout_ms` (default 15000) and `rate_limit_rpm` (default 60).

### Step 2 — Launch and capture the token

Start the server:

```sh
java -Xmx4G -jar fabric-server-launch.jar nogui
```

In the log, find the generated token (shown **once**):

```
[minecraft_fabric_mcp] Generated bearer token for MCP server. Save this value — it is shown only once:
[minecraft_fabric_mcp]   Authorization: Bearer 9c1f9a…
```

Have the user copy the token somewhere safe — Phase 4 needs it. To rotate it
later, delete `bearer_token` from `config.json` and restart. **Never commit the
token or the config file that contains it.**

### Step 3 — Run as a service (optional, recommended for 24/7)

For a deployment that survives logout and reboots, wrap the server as a
service: **systemd** on Linux, **NSSM** or Task Scheduler on Windows. The mod's
[`docs/setup-dedicated-server.md`](https://github.com/chapmanjw/minecraft-java-fabric-mcp-server/blob/main/docs/setup-dedicated-server.md)
has ready-to-paste `fabric-mcp.service` and NSSM commands plus a locked-down
`minecraft` user. Walk the user through it only if they want it now.

### Step 4 — Verify it's listening

```sh
curl http://:8765/healthz
# → {"status":"ok"}
```

Use `localhost` if testing on the server itself, otherwise the host's LAN
IP/hostname. `/healthz` needs no auth even when `auth_required` is on, so a
plain `curl` confirms reachability independent of the token.

---

## Restricting the tool surface (optional)

The mod groups its world tools into **ten domain categories** and tags each tool
with one **access level**. With no config, an operator gets a lean default: the
seven default-on domains at `write` access, about 102 tools. This is plenty for
the world builder and keeps the surface small. Touch this only if the user
wants to widen the surface or lock it down further. (There is an eleventh
category, `client`, but it is served only by the separate `minecraft-java-client`
inspection endpoint — never the world server — and is configured there.)

### The ten categories

| Category | What it covers |
|---|---|
| `blocks` | block read/write, block entities |
| `structures` | structure save/load/file ops |
| `world` | level, world border |
| `entities` | entity query/spawn/edit |
| `players` | player info, inventory, messaging, gamemode |
| `items` | inventories, item stacks, item modify |
| `gameplay` | scoreboards, boss bars, advancements |
| `scripting` | commands, functions, schedule, events, data storage/attachment |
| `registries` | recipes, loot tables, tags, content/resource registries, fluids |
| `server` | server status/MOTD, save, datapack list/toggle |

**Default-on** (registered with no config): `blocks`, `structures`, `world`,
`entities`, `items`, `scripting`, `server`. **Opt-in** (off until you add them):
`players`, `gameplay`, `registries`.

### The access axis

Every tool is `read`, `write`, or `admin`, ranked `read :8765/mcp`) and, for a remote setup, the **bearer token**.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [chapmanjw](https://github.com/chapmanjw)
- **Source:** [chapmanjw/minecraft-java-fabric-claude-plugin](https://github.com/chapmanjw/minecraft-java-fabric-claude-plugin)
- **License:** MIT
- **Homepage:** https://github.com/chapmanjw/minecraft-java-fabric-mcp-server

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-chapmanjw-minecraft-java-fabric-claude-plugin-setup-server
- Seller: https://agentstack.voostack.com/s/chapmanjw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.