@layergen/mcp

@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

• Sign in at layergen.ai
• Open Settings → API
• 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.