@layergen/mcp — Layergen for Claude (and any MCP host)

A Model Context Protocol server that exposes Layergen — text-to-3D, image-to-3D, retexture, remesh — as native tools inside Claude Desktop, Cursor, or any other MCP-compatible host.

Once installed, you can ask Claude things like "generate a low-poly oak tree sized for 32 mm tabletop printing and save the STL" and Claude will call the right tools end-to-end.

Setup

1. Get a Layergen API key

1. Sign in at layergen.ai
2. Open Settings → API
3. Click "Set up MCP in 60 seconds" for the guided flow, or use the manual form below if you want custom scopes / labels / daily caps. Either way the lg_live_… plaintext is shown once — save it now.

Billing. API generations bill against your subscription credits first, then your pay-per-gen wallet (cents-denominated, separate from the web app's billing). Pricing for wallet path: 10¢ draft / 30¢ HD / 20¢ retexture. Repair, remesh, caption, and expand-prompt are free. First API key creation grants a 30¢ welcome bonus on the wallet (= 3 free draft generations).

2. Add the server to your MCP host

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "layergen": {
      "command": "npx",
      "args": ["-y", "@layergen/mcp"],
      "env": {
        "LAYERGEN_API_KEY": "lg_live_paste_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You should see the Layergen tools appear in the tools panel.

Cursor / Continue / other MCP hosts

Same command + args + env shape — refer to your host's docs for where the config file lives.

3. Verify

Ask Claude: "What's my Layergen account status?" — it should call get_profile and report your plan + remaining credits.

Tools

Creative + meta

| Tool | What it does | Scope | |---|---|---| | generate_text_to_3d | Text prompt → textured GLB / STL / FBX | generate | | generate_image_to_3d | Reference image → 3D model | generate | | retexture_mesh | Same geometry, new PBR textures | generate | | remesh_mesh | Resize / retopologise / scale to print height | generate | | get_generation_status | Poll an in-flight task | generate | | cancel_generation | Cancel + (often) refund a running task | generate | | expand_prompt | Rewrite a short prompt into a detail-rich one | generate | | caption_image | Vision caption / 3D-prompt extraction | generate | | list_generations | Recent generation history | read | | get_profile | Account, plan, remaining credits + pay-per-gen wallet balance | read | | topup_wallet | Start a Stripe Checkout session for $5 / $20 / $50 wallet top-up — returns a URL the user clicks to pay | generate |

Generate-style tools poll synchronously up to ~75 s per phase. If a job is still rendering at the deadline, the tool returns the in-flight task_id so Claude can follow up with get_generation_status.

Repair (run locally on STL bytes)

| Tool | What it does | |---|---| | score_mesh | Returns 0–100 print-readiness score, structured issues, full stats — non-destructive | | repair_mesh | Auto-fix pipeline: merge dupes → remove floating shells → fill holes → remove non-manifold | | add_base_plate | Adds a footprint-sized plate. Padding + thickness auto-clamped for sub-mm models | | decimate_mesh | Quadric edge collapse to a target triangle count |

All four take input as either mesh_url (HTTPS, e.g. a Meshy CDN URL from a prior generation) or mesh_base64 (data URL or raw base64). Output is binary STL returned as base64 in the structured meta. 25 MB raw input cap. The repair logic is the same code that runs in the web app's "Auto-fix" button (extracted to packages/mesh-repair/).

Example prompts

Make me a sub-millimetre dragon mini and save the STL to my downloads folder.

Caption this image and generate a 3D model from the description.

Take generation 019dd926-… and retexture it as weathered bronze.

List my last 10 generations and tell me which had the highest polycount.

What's my balance? (get_profile shows subscription credits + wallet)

Top up my wallet by $20. (topup_wallet returns a Stripe Checkout URL)

Configuration

| Env var | Required | Purpose | |---|---|---| | LAYERGEN_API_KEY | yes | Key from Settings → API | | LAYERGEN_API_URL | no | Override the API base URL (default https://layergen.ai). Useful for testing against a Vercel preview deploy. |

Troubleshooting

Server fails to start, host reports an error. Most likely your API key is missing or malformed. The server logs the failure to its stderr; in Claude Desktop, check Developer → Logs. The error message will be one of:

• LAYERGEN_API_KEY is not set — fix: paste the key into the env block
• LAYERGEN_API_KEY does not look like a Layergen key — fix: re-copy from Settings → API; ensure the value starts with lg_live_

Tools list is empty in the host UI. Restart the host after editing config. Some hosts cache the tool list per session.

Tool call returns Auth failed: Invalid or revoked API key. Your key was revoked. Create a new one in Settings → API and update your config.

Tool call returns Permission denied: API key missing required scope. Your key lacks the generate or read scope the tool needs. Revoke it and create a new key with all scopes checked.

Generation tool returns still rendering after 75s. Normal for hd quality, large prompts, or busy periods. Claude can call get_generation_status with the returned task_id to follow up.

Development

This repo lives at mcp/ inside the main Layergen monorepo while it's pre-1.0. Once the API surface stabilises it'll move to its own repo.

cd mcp
npm install
npm test                         # unit + smoke tests, no API key needed
LAYERGEN_API_KEY=lg_live_... npm test   # also runs the live get_profile test

To use a local checkout from Claude Desktop without publishing to npm:

cd mcp
npm link
# then in your claude_desktop_config.json, swap to:
#   "command": "layergen-mcp",
#   "args": [],

License

UNLICENSED — internal Layergen tooling for now. Public license + npm publish TBD.