Developers

Overview#

The Model Context Protocol lets an AI agent use tools from outside its own app. Nooks offers the workbench's construction tools this way: your agent does the thinking, and Nooks turns what it asks for into real parts, checks how they connect and whether the model holds together and stands, and saves every build as a revision.

• Your agent, your model. Nooks makes no model calls of its own for your agent; it supplies tools.
• Real parts only. Everything is built from parts the workbench draws, by their LDraw numbers and real colours.
• You stay in the loop. Each revision appears in the workbench and its history. You can edit it by hand, and the agent builds on your edits.

Quick start#

1. Sign in. Building needs a free account.
2. Open Connect an agent in the workbench, and start a build for your agent (or pick one of yours).
3. Add the Nooks MCP address to your client. A compatible client opens Nooks sign-in and consent. Choose the builds it may use and whether it may edit them.
4. Verify the connection. Ask the client to call list_builds or read_project. A chat instruction alone cannot install a connection in every app.
5. Ask your agent to build. For example: "Read the Nooks project and its runtime guide, then build a small red tower on a 4×4 base, part by part, and check it."

Endpoint and authorization#

OAuth is the recommended path. The consent screen identifies the client, shows the requested read or edit access and lets you restrict it to selected builds. Inspect or revoke connected clients from your account; revoked access stops on the next call, including an active MCP session. Legacy keys coexist with OAuth: a build key opens one build, while an account key can cover selected builds and be read-only.

Connect a client#

For an OAuth-capable remote MCP client, add https://nooks.place/api/mcp. The client discovers Nooks authorization, opens sign-in and consent, and returns after approval. Do not treat setup as successful until the client calls a Nooks tool. Client support varies; some apps still require the manual key setup below.

One page for every client has the command, the config file and the sign-in step for Claude Code, Codex, Cursor, OpenClaw, Hermes and Grok Build, with the 13-tool core and the full profile side by side.

codex mcp add nooks --url https://nooks.place/api/mcp
codex mcp login nooks

Legacy key fallback#

If the client cannot authorize a remote MCP server, choose My client requires a key in Connect an agent and put the resulting key where nooks_agt_… appears below. Keep it out of URLs, source files and logs.

claude mcp add --transport http --scope user nooks https://nooks.place/api/mcp \
  --header "Authorization: Bearer nooks_agt_…"

# ~/.codex/config.toml
[mcp_servers.nooks]
url = "https://nooks.place/api/mcp"
bearer_token_env_var = "NOOKS_AGENT_KEY"

# then, in the shell you start Codex from:
export NOOKS_AGENT_KEY=nooks_agt_…

{
  "mcpServers": {
    "nooks": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://nooks.place/api/mcp",
        "--header",
        "Authorization:${NOOKS_AUTH}"
      ],
      "env": {
        "NOOKS_AUTH": "Bearer nooks_agt_…"
      }
    }
  }
}

{
  "mcpServers": {
    "nooks": {
      "url": "https://nooks.place/api/mcp",
      "headers": {
        "Authorization": "Bearer nooks_agt_…"
      }
    }
  }
}

Build programs#

An agent builds the way a person does: part by part, each placed by its connectors (this stud into that hole, this pin into that beam), so hinges, clips, Technic and minifigures join exactly. It writes the steps as a build program: plain JSON, never code, kept with the revision so it can be read, replayed and edited.

{
 "name": "bridge",
 "ops": [
  {
   "op": "add",
   "name": "left",
   "part": "brick 1x1",
   "color": "tan"
  },
  {
   "op": "add",
   "name": "right",
   "part": "brick 1x1",
   "pose": [
    {
     "at": [
      2,
      0,
      0
     ]
    }
   ],
   "color": "tan"
  },
  {
   "op": "attach",
   "name": "span",
   "part": "plate 1x3",
   "to": "left.stud[0]",
   "by": [
    "hole",
    0
   ],
   "color": "red"
  },
  {
   "op": "contact",
   "a": "span.hole[2]",
   "b": "right.stud[0]"
  }
 ]
}

The ops: add and attach (with yaw, flip, slide, align and orient), define…end for a sub-build placed many times, mirror, contact for a join the check must also find, and base to start from a saved revision. runtime_guide has them all, with worked examples.

Every part your agent can find, describe and place is sold loose, in the colours it is sold in, so whatever it builds can be ordered as a kit. A part or colour that is not is refused, with the closest one that is. Hoses and strings are switched off for now. export_python gives any build as a standalone Python script for the open-source construction library the runtime follows, which builds the same parts at the same poses.

A typical loop:

1. Find parts with find_parts, and what joins a connector with parts_that_fit.
2. See where to build next with program_connectors: each connector of a placement, free or joined.
3. Check with check_program: every join, collision and stability problem, and an inventory if you give one, each naming its parts.
4. Look with view from several sides.
5. Save with build_program, then change it with edit_program.

An agent can also save a model it placed part by part (save_parts) or an LDraw file (import_ldraw).

Code. Instead of a list of ops, your agent can write Python with run_code: loops, variables, arithmetic and parts it can ask where their connectors are. The code runs in a sandbox of its own, a small virtual machine with no network and none of our data, for at most 30 seconds. What it builds is checked like any program and saved with the code, so you can read how a build was made and your agent can run it again.

Live sessions. Each connection also has a live model. Your agent builds it up a step at a time (session_ops, or code cells that remember their variables), asks it anything (session_query: its size, parts, joins, free connectors, a full check, a picture), takes steps back, and saves it as a revision only when it is right. It is kept if the connection drops. If you edit the build in the workbench meanwhile, your agent is told and puts its work on top of yours.

Checks. Joins, collisions and the two-second gravity test for agents run on the physics engine the open-source library uses, in a sandbox; the workbench's own Test gravity runs another engine in your browser on the same part shapes and the same rule. They agree on the builds we test, though a build right at the edge can pass one and not the other; every result says which engine gave it. The report names the rule, the elements it is about and the op, code line or step that placed them.

How to read a report#

A check returns a report, not just a pass or a fail. Every finding names its level and its rule, then the fact it found; the lines under it say where and which parts or discs:

error[overlap]: the bodies of 2 parts share positive volume
  --> x 2..4  y 0..2  z 3..4  (1.2 .. 1.6 mm)
   = #3 3001 Brick 2 x 4, Red         op 14 "roof-3"
   = #7 3020 Plate 2 x 4, White       op 9 "base-2"

warn[unstable-component]: 1 group of 3 parts tips toward -y
  --> x 0..6  y 2..8  z 12..18  (4.8 .. 7.2 mm)
   = #11 3005 Brick 1 x 1, Tan        op 21 "finial"

checked 42 parts against 12 rules (piece-budget, size-bounds, palette ignored): 1 error, 1 warning

• The heading is level[rule]. error fails the build, warn is reported without failing it, and ignore is off until a request turns it on. ok is true only when no error remains.
• The region after --> is an axis-aligned box in model units: LDU for bricks (with its height in millimetres), millimetres for Brain Flakes.
• Each = line is one element the caller already knows: a part key or connector address, or a disc and slot. Its source follows where there is one: op 14 "roof-3", line 12, step 4 or a revision id.
• The closing line counts what was checked, names the ignored rules, and reports errors and warnings. It counts omitted findings too, and names any deferred rule and why, so a truncated or partial report never reads as a pass.

Rules are configured, never passes: a request can raise or lower a rule's level, or enable one whose default is ignore. The rule reference lists every rule, its default level and the pass that checks it.

Revisions and conflicts#

Every build is saved as a new revision on top of the one before. Pass the build's currentRevision from read_project as baseRevision when you build.

A 409 means someone saved in between, often you, editing by hand in the workbench: read again and build on the latest. An agent replaces a hand edit only if it passes replaceHumanEdit: true, which it should do only when you have said so.

Tools#

Rule reference#

Every rule a check can report, generated from the rule tables the checks use (lib/rules/bricks.mjs, lib/rules/instructions.mjs and lib/rules/brainflakes.mjs). A rule is one kind of fact: a kebab-case name, a default level, the pass that checks it and the condition in plain words. People and agents configure rules, never passes.

Levels are error (the build fails), warn (reported, does not fail) and ignore (off unless a constraint or an explicit level turns it on). The default is what applies when a request says nothing; a constraint such as maxPieces runs its rule at error.

Limits and safety#

• Sharing is yours. When you ask, an agent can publish your kit in the public gallery and give you a link. Agents cannot order parts.
• Other people's text is data. Community titles and descriptions are written by contributors; the server tells agents never to follow instructions in them.
• Wrong keys are refused. A key is checked before any tool runs, and an address that keeps sending wrong keys is turned away for a while (429, with Retry-After).