Drive Pinwing from any MCP client — setup, the 37-tool reference, and prompt examples

Overview

The MCP server is a thin wrapper over the Pinwing /v1 REST API — it forwards your bearer token and exposes 37 tools covering the full pipeline: import/upload models, quote costs, create single and batch renders, poll status, manage overlays/textures/ environments, and download results (streamed or via presigned direct-from-storage URLs).

It runs in two transports:

• Hosted (Streamable HTTP) — nothing to install; point your client at the hosted URL and pass your key. Best for most users.
• Local (stdio) — run the server on your machine with node. Needed for uploading models from local file paths.

Everything the tools can do is scoped by your API key. The key implies the workspace — a personal key operates on your personal library and bills you; a workspace-bound key (editor role or above) operates on that team workspace and bills its owner. There is no workspace parameter on any tool.

Quick start (hosted)

1. In Studio, open the account menu → API → Keys, and create a key. It looks like pinwing_sk_... — copy it now; it is shown once.
2. Add the server to your MCP client. For a streamableHttp-capable client (e.g. Claude Code, Claude Desktop):

{
  "mcpServers": {
    "pinwing": {
      "type": "streamableHttp",
      "url": "https://mcp.pinwing.ai/",
      "headers": {
        "Authorization": "Bearer pinwing_sk_..."
      }
    }
  }
}

3. Restart the client. Ask it something like "Import the GLB at <url> and render a 4K turntable on a white background" — the agent handles the tool calls.

The hosted server stores no key — each request carries its own Authorization header, so one endpoint serves every user. mcp.pinwing.ai is the canonical endpoint; the original mcp.dx.gl host remains fully supported — same server, same keys.

Local install (stdio)

Use the stdio transport when you want the agent to upload models straight from local file paths (upload_model with filePath), which the hosted transport can't reach.

git clone https://github.com/harrimy/dxgl
cd dxgl/api/mcp
npm install

Configure your client to launch it. Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pinwing": {
      "command": "node",
      "args": ["/absolute/path/to/dxgl/api/mcp/index.js"],
      "env": {
        "DXGL_API_KEY": "pinwing_sk_..."
      }
    }
  }
}

The stdio server sets allowLocalFiles: true, enabling upload_model to read a GLB from a path on the same machine. The hosted transport disables this for safety.

Authentication and keys

Every tool call forwards your key as Authorization: Bearer pinwing_sk_... to the REST API, which validates it and applies scope and role checks. Mint and revoke keys in Studio → account menu → API → Keys.

• Personal vs workspace-bound — a plain key acts on your personal workspace; a workspace-bound key (created with the workspace picker, editor role or above) makes every tool operate on and bill that workspace. get_account reports which workspace a key is bound to.
• Presigned URLs are secrets — get_download_url and get_model_file_url return short-lived links that download directly from storage with no auth header. Until they expire (default 1 h) they are unauthenticated capability links — treat them like passwords.

Tools

37 tools, grouped.

Models

Renders

Billing

Downloads — each returns a URL. API-streamed URLs need your Authorization header; the presigned tools don't.

For large files, prefer the presigned tools: get_download_url (render assets) and get_model_file_url (source GLB) return short-lived URLs that download directly from storage with no Authorization header — ideal for ProRes videos and dataset ZIPs that run to tens of GB, and for handing a download to another system.

Overlays

Textures and environments

Render settings

Render settings are passed to create_render / create_batch_renders / quote. The schema mirrors the server validator 1:1, so anything the Studio UI can author is reachable.

Video quality tiers

The JSON enum values are frozen for API stability; the display labels were renamed and no longer match one-to-one. Pass the JSON value as quality.

When quality is omitted the server defaults to standard (HD, 4 credits/sec) — a bare 6-second render bills 24 credits, not 6. Always pass quality explicitly.

Dataset tiers

Camera paths

turntable (default), hero-spin, showcase, zoom-orbit, reveal, keyframes — passed as the effect field.

Full surface

All optional; see each tool's input schema for exact ranges:

• Output & motion — output, aspect, length, easing, sweepAngle, easeOutRatio, amplitude, zoomStart/zoomEnd, scaleFrom, coverage, strictCredits (hard-fail 402 instead of the free-pool fallback — the unattended-run guard)
• Model transform — panX, tiltX, rollZ (model yaw → pitch → roll, in that order, −180…180), scaleX/scaleY/scaleZ (per-axis scale; negative mirrors that axis, uniform is a no-op; 0.01–20), translateX/translateY/translateZ (position offset, ±20; positive translateY lifts off the ground), hiddenMeshNames (exact case-sensitive mesh names; unknown names are a silent no-op — verify against the GLB)
• Camera framing — rotateY (orbit start angle — moves the camera, not the model), zoom (0.5 = far, 2.0 = close)
• Animation — animation, animationSpeed (−10…10, non-zero)
• Keyframe / fly-through — camera, keyframes[], startAngle/endAngle, startTilt/endTilt, startZoom/endZoom, startFov/endFov, easeInSeconds/easeOutSeconds, kfSegmentDuration, loop
• Background — bgColor, bgImageId, bgAlign, bgGradient
• Filter / post — filter, vignette, bloomEnabled/bloomStrength, dofEnabled/dofStrength, n8aoEnabled/n8aoIntensity, swayEnabled/swayIntensity
• Shadows & reflector — shadows, shadowMode, shadowDarkness, shadowSoftness, reflector, reflectorMix, reflectorFade, reflectorDepthBlur
• Environment / IBL — envId, envRotation, envExposure, envMode, envOpacity, envBlur, envScale, envTint, envTintStrength
• Lighting — spotlightIntensity, lightsIntensity, ambientIntensity, glossIntensity, keyLightColor, fillLightColor
• Materials & decals — materialEdits (per-material overrides keyed by material name), decals[]

Examples

"Import the GLB at https://example.com/chair.glb and render a 4K turntable video with a white background."

The agent calls ingest_model with the URL, create_render with { quality: "4k", bgColor: "#ffffff" }, polls get_render until done, and returns the URL from download_render.

"How much would it cost to render 50 models at 4K?"

The agent calls quote with 50 entries of { quality: "4k" } and reports 4,800 credits (fifty 6-second 4K turntables at 16 credits/second).

"Render the chair facing the label, leaning slightly toward the camera, with the packaging hidden."

The agent calls create_render with:

{ "quality": "share", "panX": 35, "tiltX": -12, "zoom": 1.3, "hiddenMeshNames": ["Packaging"] }

panX/tiltX/rollZ rotate the model (yaw first, then pitch, then roll); rotateY instead offsets where the camera's orbit starts. hiddenMeshNames needs exact case-sensitive mesh names from the GLB — unknown names silently hide nothing.

HTTP transport (self-hosting)

The hosted mcp.pinwing.ai endpoint is the same code you can run yourself. Serve multiple users without local installs by running the HTTP transport:

cd api/mcp
node http.js

DXGL_API_KEY is not set on the server — each client sends its own key on every request. The endpoint is Streamable HTTP (stateless: a fresh MCP session per request, bound to the caller's key). A legacy SSE transport is also served at GET /sse + POST /messages for older clients. Health check: GET /health.

Troubleshooting

• 401 Unauthorized — the key is missing, malformed, or revoked. Confirm the client sends Authorization: Bearer pinwing_sk_... (hosted) or that DXGL_API_KEY is set (stdio).
• Render cost surprise — you omitted quality, so it defaulted to standard (HD, 4 credits/sec). Pass quality explicitly; use quote first to confirm.
• hiddenMeshNames hid nothing — mesh names are case-sensitive and must match the GLB exactly; an unknown name is a silent no-op. Inspect the model to get exact names.
• Large downloads stall or need re-auth — use the presigned tools (get_download_url, get_model_file_url) instead of the API-streamed ones for multi-GB assets.
• Local file upload fails on the hosted server — filePath uploads only work on the stdio transport (allowLocalFiles). Use base64, or run locally.