Connect an AI coding agent (MCP)

Quarry can be driven by an external AI coding agent — Claude Code, GitHub Copilot, or anything that speaks the Model Context Protocol. The agent gets Quarry's whole editing suite as tools: it can read the world, place blocks and shapes, paint biomes, generate structures, toggle Vibrant Visuals, take screenshots to see what it built, and export .mcworld / .mcstructure files.

No API key is needed in Quarry itself: your agent is the brain and Quarry is its hands — it can look at the world, build, screenshot, look again, and iterate.

Why a bridge is needed

Quarry runs entirely in your browser tab, and browsers can't accept incoming connections. So a tiny program — mcp/server.mjs, shipped in the repo — sits between the two. There are two ways to connect it:

Local — a plain ws://localhost link to the bridge on your machine:

your AI agent  ⇄ (MCP/stdio) ⇄  mcp/server.mjs  ⇄ (ws://localhost) ⇄  Quarry tab

Cloud relay — a secure wss:// link through Quarry's relay Worker:

your AI agent ⇄ (stdio) ⇄ mcp/server.mjs ⇄ (WSS) ⇄ Quarry relay ⇄ (WSS) ⇄ Quarry tab

Either way, the agent talks MCP to that program; the program relays each tool call to your open Quarry tab, which runs it on the live world. Every edit goes through Quarry's normal undo history, so anything the agent does is undoable — and exports stay byte-for-byte non-destructive, exactly as with hand edits.

Which one?

It comes down to how Quarry's page is served, not just where the agent runs:

Cloud relay — use this on the deployed site (https://quarry.refrag.com). A secure (https) page can't open an insecure ws:// connection, so the local link is unavailable there — even if the agent is on your own machine. The relay uses wss://, so it works from https in every browser.
Local — use this only when you've opened Quarry from a local http server (the dev server at http://localhost:5173), with the agent on that same machine. Because the page is http, the browser allows the ws://localhost link, with no cloud round-trip. So "local" really means Quarry's web server and the agent are the same machine, not just "the browser and agent are."

The panel picks the right one for where you've opened Quarry automatically.

Getting the bridge program

The bridge is a tiny Node program (Node 18+). You don't need to clone Quarry — download the self-contained, single-file build:

curl -fsSL https://quarry.refrag.com/quarry-mcp.mjs -o quarry-mcp.mjs

(The Cloud relay panel gives you a copy-paste snippet with this line already filled in. If you do have the repo checked out, node mcp/server.mjs / npm run mcp works identically.)

Setup (local)

Open Quarry from a local http server first — run npm run dev and use http://localhost:5173. (Local mode won't connect from the deployed https site; use Cloud relay there.)

Download the bridge (above), or use your checkout.
Register it with your agent. For Claude Code:
```
claude mcp add quarry -- node /absolute/path/to/quarry-mcp.mjs
```
(Or just run node quarry-mcp.mjs in a terminal to start it and read the token.)

The bridge prints a pairing token to its output, for example:

[quarry-mcp] listening on ws://127.0.0.1:7331
[quarry-mcp] pairing token: 3f9a1c0b7e2d4a55

In Quarry (opened from http://localhost), load or create a world, open the app menu and choose AI agent (MCP)… — it opens in Local mode; click Connect and paste the token. The status dot turns green.
Ask your agent to use the Quarry tools — for example "read the area around 0,64,0, then build a small stone tower there and show me a screenshot."

Setup (cloud relay)

Use this on the deployed site (https://quarry.refrag.com) — for any agent, on your own machine or remote — and any time the agent and Quarry's web server aren't the same machine. The agent and the tab meet in a private room on Quarry's collaboration Worker; no inbound ports or tunnels are needed (both sides connect out).

It's tied to your GitHub sign-in (the same one collaboration uses), so the agent pairs to your account — you set it up once and never reconfigure it.

In Quarry on the deployed site, open AI agent (MCP)… — it opens in Cloud relay mode (if you're on http://localhost, use the "On the deployed site, or the agent is elsewhere? Use the cloud relay" link). Sign in with GitHub if you haven't. Quarry shows your stable room (mcp-<your-id>) and a personal token, plus a ready-to- paste snippet. Click Connect — your tab joins your room and waits.
On the agent's machine, run the snippet from the panel — it downloads the bridge and registers it with your personal token (no room needed — the bridge derives it from the token):
```
curl -fsSL https://quarry.refrag.com/quarry-mcp.mjs -o quarry-mcp.mjs
claude mcp add quarry \
  --env QUARRY_MCP_RELAY=wss://your-collab-host \
  --env QUARRY_MCP_TOKEN=your-personal-token \
  -- node ./quarry-mcp.mjs
```
The bridge reports tab attached once it finds your Quarry tab. Because the token is stable, this config keeps working across sessions and machines — no removing/re-adding the server. (For Copilot CLI, put the same env in the quarry entry of ~/.copilot/mcp-config.json.)
Drive it exactly as in local mode. Large results (screenshots, exported worlds) are split into chunks and reassembled automatically, so they stream across fine despite the relay's per-message size limit.

If your token ever leaks, click rotate token in the panel — it invalidates every old agent token at once; re-copy the new snippet to your agent.

Self-hosting / local dev: a relay Worker without SESSION_SECRET configured stays in the original ad-hoc mode (a random room + pairing token, no GitHub) — the panel falls back to that automatically.

What the agent can do

See: world_info, get_block, get_region, find_blocks, list_blocks, analyze_region (block histogram of a box or the current selection).
Build (all undoable): set_block, fill, hollow_box, walls, line, sphere, cylinder, clear, replace_blocks (find & replace, exact or any-state), place_text (extruded block lettering — optional pixel font, and emoji become color-matched blocks), extrude_face (pull/push a connected face like the Extrude tool), flood_fill (paint bucket), undo, redo. fill/hollow_box/walls/clear/replace_blocks accept an optional mask expression (the Mask panel grammar, e.g. surface and not block:water) gating which cells are written.
Nature: place_nature (one biome-aware procedural tree or rock, or a single stalactite/stalagmite with kind: "dripstone" — deterministic with a seed) and scatter_nature (the Nature tool's brush: biome-appropriate trees/shrubs/flora/detail over surface columns, or erase). Turn on scatter_nature's spikes layer to grow speleothems on cave floors and ceilings instead, in dripstone, sulfur or amethyst.
Generate terrain: generate_chunks runs the world generator — vanilla-style Java-worldgen terrain (optional trees/ores/snow) into empty chunks, as one undoable op. Area forms: a block box, a radius around a point, or rings around existing chunks. dimension says where the chunks go and generator says which dimension's terrain to build, so the two can differ — fit (clamp or sea-level) then decides how the Y range is placed. Decorations and structures run in every dimension now — Nether fortresses, bastions and fossils, and End cities, all where the seed puts them.
Find structures: locate_structure is a seed-exact /locate for the current worldgen seed — the nearest village, stronghold, monument, shipwreck… as a position, distance, and height hint, computed without generating a single chunk. Pair it with generate_chunks to materialize the area.
Build with code — the fast path: run_build runs an agent-authored build(api) program in Quarry's sandbox and commits the whole result as one undoable op — far faster (and far fewer tokens) than streaming hundreds of primitive calls. get_build_api returns the DSL plus the craft rules (stair orientation, two-block doors, torch support, roof technique). Build code can pass waterlogged: true alongside a block's states to leave water in the cell, so docks, piers and sunken wrecks sit in the water rather than on it. mode:'edit' seeds the volume with the existing world so code can read-and-modify (carve, re-roof, terraform).
Build from a 3D model: import_model voxelizes a standard model file (glTF/GLB, OBJ, FBX, STL) into blocks as one undoable op — the agent can even author the mesh itself (OBJ text is easy to write) and let Quarry rasterize it, color-matched to a palette (all, wool, concrete, terracotta, natural), hollow or solid, scaled/rotated, with the same save contract as run_build.
Orient first: world_overview — a cheap, token-bounded LOD map of the whole dimension (dominant biome, terrain-height bucket, and which regions are already built) with no per-block reads. Best first call on an unfamiliar world or to recall where earlier builds are; the map coarsens automatically so it stays small on huge worlds, and it never forces the world to fully load. Pass min/max [x,z] to zoom into a region.
Plan against terrain: surface_scan (a heightmap + surface materials over an area, so builds sit on the real ground) and locate_blocks (find blocks by name within a box).
Generate once, stamp many: save_structure snapshots a box into the library; list_structures lists it; place_structure stamps it anywhere — with optional rotation (90° steps) and mirror so repeated pieces don't look cloned. get_structure reads one back (metadata or full contents); rename_structure / delete_structure manage the library.
Remember & match the style: list_builds is the agent's per-world memory of what's been built (labelled regions with bounds + dominant materials, persisted across sessions); get_style infers the artist's palette and role mix (trim, glass, greenery, colour accents) from saved structures and past builds so new work fits in; set_style_notes records a declared intent ("medieval, spruce + stone") for the agent to follow.
Biomes (all undoable): get_biome, set_biome (per block — Bedrock biomes are 3D), fill_biome (biome a box, e.g. a selected room), flood_fill_biome (fill an enclosed air space — a sealed room or cave chamber — from an interior point, walls included), fill_column_biome, list_biomes. Pair with set_biome_view mode volumes to see interior biomes through walls in a screenshot.
Mobs (all undoable): list_entity_types (what this world can spawn — the vanilla palette plus any custom entities its add-ons define), list_mobs (each with a stable mob_id), place_mob (with facing + variant, or a random one), move_mob, set_mob_facing, set_mob_variant, delete_mob, and bulk delete_mobs over a box. place_mob takes an add-on's own identifier as readily as a vanilla one.
Selection & clipboard: select, magic_select (flood-select a connected or same-material region into a mask-aware selection), copy, paste, delete_selection, stack_selection (repeat along an axis), move_selection / clone_selection (offset the contents, mask-aware).
Look: screenshot, orbit_capture, look_at.
Visuals: set_vibrant_visuals, set_render_option, set_biome_view.
Export: export_mcworld (with an optional compact to drop data Minecraft ignores or rebuilds — the world plays identically but is no longer byte-for-byte identical to the source), export_mcstructure.

A smart build loop

A capable agent decomposes a request and works in passes: world_overview to get the lay of the land → surface_scan to find flat ground → run_build (or place_structure) for each piece → screenshot to see the result → adjust and repeat. Building a village becomes: scan the area, run_build one house, save_structure it, then place_structure it across the flat columns with variation — a handful of calls instead of thousands.

Staying safe

In local mode the bridge listens on 127.0.0.1 only, checks the page origin, and requires the pairing token, which keeps stray web pages from connecting. In cloud relay mode the room is gated by a private, high-entropy room id plus the pairing token (and the relay only accepts browser connections from Quarry's own origin); anyone with both the room and token can drive your tab, so treat the snippet like a password and rotate it with New room if it leaks.

Either way, treat this as opt-in convenience rather than a hardened sandbox. Because every edit is undoable and exports are non-destructive, anything an agent does is easy to walk back. Keep the tab open (and focused, for screenshots) while the agent works.