@3dpolygen/mcp

The Polygen MCP server, over stdio — drive the Concept → 3D Models → Textures pipeline from Claude Code, Claude Desktop, Cursor, Codex, or any MCP host.

Requires a Polygen account on Indie or higher and an API key.

Install

Nothing to install — point your host at npx.

{
  "mcpServers": {
    "polygen": {
      "command": "npx",
      "args": ["--yes", "@3dpolygen/mcp"],
      "env": { "POLYGEN_API_KEY": "plg_live_…" }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.polygen]
command = "npx"
args = ["--yes", "@3dpolygen/mcp"]

[mcp_servers.polygen.env]
POLYGEN_API_KEY = "plg_live_…"

Configuration

| Variable | Required | Default | Notes | |---|---|---|---| | POLYGEN_API_KEY | yes | — | Scoped, revocable key (plg_live_…), minted in Account → API keys. Shown once. | | POLYGEN_API_URL | no | https://www.3dpolygen.com | Override only for staging or a self-hosted origin. | | POLYGEN_REQUEST_TIMEOUT_MS | no | 120000 | Generation is async — poll polygen_run rather than raising this. |

The server writes the origin it is serving to stderr on startup, so your host's MCP log shows which Polygen it is talking to. Startup failures exit 78 with the reason and a remedy rather than starting a server that would fail every call.

There is also a remote Streamable HTTP endpoint at https://www.3dpolygen.com/api/agent/mcp, which needs no install and cannot go stale. Both transports serve the same implementation.

What it exposes

Tools — polygen_onboard, polygen_contracts, polygen_elevate, polygen_generate, polygen_run, polygen_price, polygen_style, polygen_projects, polygen_assets.

Prompts — polygen-concept, polygen-kit-sheet, polygen-style-from-image, polygen-elevate-check.

Resources — polygen://product-map, polygen://craft/concept, polygen://craft/kit-sheets, polygen://craft/style-aspects, polygen://capabilities, polygen://contracts, polygen://projects, polygen://styles.

Reads, polygen_price, polygen_contracts and polygen_elevate cost no image credits; only polygen_generate spends.

The order that works

1. Bind a style — persistent art direction is the point. Generating before binding is the most common way to get mediocre output from a capable pipeline.
2. Read the contracts (polygen_contracts, free) — returned whole.
3. Elevate (polygen_elevate, free) — returns the prompt that would generate, plus a spendable handle.
4. Read the opening clause — it decides camera, framing, and whether the result reads as an extractable asset.
5. Generate with the handle — the resolved input is re-checked; if anything moved, the call fails and names the field rather than spending.

Protocol

Dual-era. Serves the 2026-07-28 revision (per-request _meta, server/discover, no handshake) and clients still opening with initialize on 2025-11-25. An unsupported version is refused with -32022 naming the supported set rather than being silently downgraded.

Development

This package is a distribution shell, not a second implementation. The server lives in website/lib/mcp/ so the Next.js route can mount the same code as the HTTP transport; npm run build bundles it here with esbuild. See scripts/build.mjs for why tsc cannot build this package.

npm run build      # bundle → dist/bin/stdio.js
npm run typecheck  # tsc --noEmit over the bundled graph
npm test           # build, then the dual-era protocol smoke

POLYGEN_MCP_BIN=/path/to/stdio.js npm run smoke points the smoke at a packed-and-installed binary, which is the only thing that proves the distribution rather than the working tree.