Coding agents & MCP

The MCP setup page gives you a command for Codex, Claude Code, Cursor, VS Code or Gemini CLI. Choose Other agents for a standard stdio configuration you can paste into any client that supports MCP. Cloud agents that cannot reach your computer need a publicly reachable deployment.

Quick installation

With Node.js 22 or later, run the same commands on Windows, macOS, or Linux:

npm i -g shaderweave
shaderweave setup

Choose your agent when prompted, or use shaderweave setup codex, shaderweave setup claude, shaderweave setup cursor, shaderweave setup vscode, or shaderweave setup gemini.

Create an API key in Account and paste it into setup’s hidden terminal prompt. You can supply SHADERWEAVE_API_KEY in the process environment for unattended setup. Restart your agent and enable its ShaderWeave tools. Ask it to list generators and estimate a render; this first check spends no credits.

For the local preview, use the website port:

shaderweave setup codex --origin http://localhost:3100
shaderweave doctor

The explicit local preview handles credentials automatically through its loopback web gateway. The setup page generates the command for the instance you are visiting.

The page’s Check connection verifies the website endpoint using your browser account. The installer independently verifies its API key before changing your agent configuration. Neither check proves that a separate agent has been restarted; confirm that ShaderWeave appears in that agent’s MCP tools.

What the installer changes

The npm package has no runtime npm dependencies or install lifecycle scripts. Running setup checks the connection, backs up an existing agent configuration, and adds the shaderweave server. Other servers and JSON comments are preserved. A conflicting server name or invalid configuration stops setup before changes are made.

VS Code custom profiles, remote containers and remote SSH workspaces have separate configurations. Use Other agents in the environment where the agent actually runs, then add its generated configuration there.

The bridge and credentials live in ~/.shaderweave/mcp/bridge.mjs and ~/.shaderweave/mcp/connection.json. Credentials and backups have owner-only permissions; no API key is written into the agent entry or printed by the installer. Agents installed for the same OS user share this connection. Rerun the installer with a new API key to rotate it. To switch to another deployment, first remove or rename the connection file, then reinstall for each agent.

Use shaderweave --help for all commands, shaderweave setup codex --dry-run to inspect proposed settings, and shaderweave doctor to verify the saved connection without writing. shaderweave config prints configuration for other clients; shaderweave mcp starts the saved stdio connection. Update with npm i -g shaderweave@latest, then rerun setup.

Existing ShaderLoom installer credentials and matching agent entries are upgraded automatically. Old connection files are retained for recovery.

Visual workflows

Ask your agent to show alternatives before creating a new asset. search_styles finds curated artwork; get_style returns a real image and its recipe. compare_styles presents 2–6 numbered directions for free. Each direction has an editor link.

Use build_recipe to validate dimensions and vary_recipe to prepare palette or seed variations. Variations are recipes, not rendered previews. Estimate the exact input before rendering within your approved budget. compare_renders compares 2–4 completed raster exports without spending additional credits.

Image-capable clients receive contact sheets and previews. Hosts supporting MCP Apps can also display an interactive choice board. Selecting a direction shares context with the agent; it does not spend credits. Other clients receive the same numbered alternatives as text and images.

The explore_directions, refine_asset, and ship_asset prompts take a brief argument. Clients can read the workflow at shaderweave://guide, the curated index at shaderweave://catalog, schemas at shaderweave://generators/{slug}, exact styles at shaderweave://styles/{id}, and owned render results at shaderweave://renders/{id}. Prompt and resource interfaces vary by client.

Available tools

The server also exposes a workflow resource at shaderweave://guide. Agents should discover settings, estimate the exact recipe, stay within your approved credit budget, then submit one job and poll it every 2–10 seconds. Failed or cancelled jobs release reserved credits. MCP cannot buy credits or change your subscription.

download_render requires an absolute output path and an existing parent directory. It checks the output extension, never overwrites a file and removes partial downloads after failure. Its limit is 200 MB. Direct HTTP clients can use GET /v1/jobs/:id/result with the same API key for downloads.

Previews fit inside 768 × 768 pixels without changing the original export. GIF previews show one frame; download the original to inspect motion. MP4, SVG and CSS remain downloadable. An unreadable preview does not delete or resize your original file. The authenticated REST preview route is GET /v1/jobs/:id/preview (also sdk.jobs.preview(id)).

Manual connection

The endpoint is /v1/mcp on your ShaderWeave website origin, using stateless Streamable HTTP. The setup page builds the correct configuration for the current hostname. Hosted access uses Authorization: Bearer YOUR_API_KEY; keep this in private client settings. Codex can read it from SHADERWEAVE_API_KEY using bearer_token_env_var.

The installed bridge uses stdio locally, forwards authenticated requests to the same endpoint, and adds local file downloads. No extra server process, public port or database is needed. Jobs, accounts, limits and credit accounting are shared with the REST API. HTTP responses use JSON rather than a long-running event stream, which fits the existing reverse proxy and single-replica SQLite deployment.

Troubleshooting

• 401: create a valid API key in Account, then rerun the installer. Revoking a key immediately disconnects clients using it.
• 402: check Billing. Renders use the same credits as the editor; no automatic overage is charged.
• 429: wait before retrying. MCP has a control-request limit and shares the REST rendering limits.
• Connection refused: keep both local services running, and use the website port rather than the internal API port. A hosted agent cannot reach your laptop’s localhost.
• Existing server / invalid config: fix the reported configuration or rename the conflicting server. Your original file is preserved.
• Node not found after restarting: reinstall using your stable Node installation. The agent entry uses the Node executable’s absolute path.
• Missing result: files are subject to the same export retention policy as the account’s export history. Rerender an expired export.
• Uninstall: remove the shaderweave entry using your agent’s MCP settings, then run npm uninstall -g shaderweave. Remove the private connection/bridge files once no other agent uses them. Revoke the key in Account to terminate access.

Client configuration references: Codex, Claude Code, Cursor, VS Code, Gemini CLI.