Codex CLI and Claude Code

Generate simulation assets from text, images, or CAD without leaving your coding workflow. This is Palatial’s public thin client: a command-line application and a local MCP server. It uploads selected inputs to the Palatial API, tracks assets, and downloads export ZIPs. Generation remains on Palatial’s hosted service. Release status: Public preview. An API READY status means outputs are available; it does not certify your simulation task.

How it works

You need a Palatial workspace API key. The coding agent calls the local MCP client, which authenticates requests to Palatial’s existing hosted API at https://dashboard.palatial.cloud/api/v1/external/. Palatial performs the generation on its servers. The client checks the returned asset ID and downloads the completed export.

MCP provides the tools the coding agent can call; it does not replace the Palatial API. This release uses your existing API and requires no new customer-hosted service. A Palatial key is separate from your other provider credentials.

Install

You need Node.js 22 or newer, a Palatial workspace API key, and Codex CLI or Claude Code. Generation and export use your Palatial workspace credits. Your coding agent’s subscription or API charges are separate. Install the versioned package from the official GitHub Release:

npm install --global https://github.com/PalatialSim/palatial-agent-tools/releases/download/v0.1.9/palatial-agent-tools-0.1.9.tgz
palatial-agent --version
palatial-agent login
palatial-agent doctor

login prompts for your workspace API key with input hidden, checks it through a read-only API call, and saves it locally. Obtain the key in Palatial dashboard workspace settings. Do not paste it into your coding-agent conversation. The npm-compatible package is distributed through GitHub Releases. It is not yet published to the npm registry. The package name @palatial/agent-tools is metadata, not a currently verified npm installation target.

Codex CLI

palatial-agent setup --client codex
codex

Start a fresh session, then ask:

List the Palatial tools and run palatial_doctor. Do not generate or export anything yet.

Claude Code

palatial-agent setup --client claude-code
claude

Use /mcp to inspect the connection, then ask for the same read-only check. To configure both clients, run palatial-agent setup –client both. Preview every planned change with –dry-run. Setup adds a server named palatial in the user’s client configuration, and for Claude Code it also installs the Palatial skill described below. Review or remove an existing server of that name first. Setup will not overwrite a skill folder it did not create, including one you have edited or replaced with a link, and it reports a non-zero result if any part of setup did not complete. It does not modify your project instructions or other servers. If you move this installation or change the Node.js executable, rerun setup. The client runs over stdio: your coding agent starts it as a local process. You do not need Docker, a local GPU, an inbound port, or your own hosted MCP server. Internet access to Palatial and its export storage is required.

Live docs and generation settings

Every MCP startup checks docs.palatial.cloud directly, compares article content with a saved snapshot, and reports added, changed or removed pages. palatial_doctor.docs reports the startup result. palatial_check_docs refreshes the check and retains the startup changes; palatial-agent docs is the CLI equivalent. The first successful check establishes a baseline. If the site is unavailable, the client starts with the packaged guidance and preserves the last successful snapshot.

For text/image generation, use mode: diffusion, or mode: parametric with effort: low or mad_max. Build settings go inside parameters; Mad Max and video builds take no build parameters. CAD has no mode. The MCP exposes rigid assets and omits shape_model, texture_model, body_type, auto_scale and replace_glass. Prefer collision_quality: auto or omission on Diffusion/Low: the MCP leaves the raw API override unset, currently selecting medium. Mad Max chooses proxies itself. See Using the API for route settings and limits.

For an asset still in INIT, inspect generation_job returned by palatial_get_asset or palatial_get_asset_details. Its native research/build status is separate: a failed job can coexist with INIT. Preserve both IDs and report errors or questions. Mad Max needs useful product evidence; a generic description may fail research before a 3D build starts.

Read changed pages before selecting affected options. A docs change does not rewrite the installed tool schema; update the package if its schema differs. The snapshot is saved as docs-snapshot.json in PALATIAL_STATE_DIR or the default local state directory. Live docs checks require no Palatial credentials or generation tokens.

Create your first asset

In either coding agent:

Use Palatial to generate a rigid plastic storage bin for Isaac Sim. Save the asset ID, check its status, and download the completed export into ./assets/storage-bin. Report which validation checks were actually performed. For an image: Use Palatial to turn ./references/bin.jpg into a rigid Isaac Sim asset. Use only that file as input. Download the completed export into ./assets/bin. For CAD: Convert ./cad/gripper.step using ./references/gripper.png with Palatial. Its up axis is Z. Target Isaac Sim and keep the export in ./assets/gripper. A CAD reference image is optional. Supply one when you want textures generated from it. Convert the file on its own and it is built untextured: Convert ./cad/gripper.step with Palatial. Its up axis is Z. No reference image. Target Isaac Sim and keep the export in ./assets/gripper. Specify the target simulator, dimensions, and articulation requirements when known. What you must state about the source frame depends on the file you upload: a direct mesh (OBJ, GLB, GLTF, STL, PLY, FBX) needs its up axis plus its scale, given either as source units or as the exact number of metres one source unit represents; STEP and IGES need only the up axis; USD files use the orientation and scale already stored in the file, so you do not supply either. Reference images can be PNG, JPEG, or WebP. Supported engine request values are isaac_sim, mujoco, and newton. Verify the output for your selected simulator; format and runtime capabilities depend on the pipeline.

Built-in guidance for your coding agent

Tool names alone do not tell a coding agent that a second create request is a second charge, or which create settings can be combined. The package ships that guidance as plain Markdown you can read and edit: a workflow overview, a full parameter reference with defaults and the rules that reject a request, worked examples for each input type, and a troubleshooting guide.

It reaches your agent two ways, from the same files:

• Any client, including Codex CLI, can call the palatial_guide tool. It is local, read-only, free, and takes a topic of overview, parameters, recipes, or troubleshooting. Clients that support MCP resources see the same four documents there too.
• Claude Code additionally loads the guidance as a skill from disk, which setup installs, so it applies without a tool call. Nothing starts it: Claude Code matches your request against the skill and loads it on its own.

To read exactly what your agent reads, without a key or a network call:

palatial-agent guide
palatial-agent guide --topic parameters

A release can change the guidance, so rerun setup after updating to refresh the installed skill.

What you can ask for in a build request

Ask for the object, real dimensions, materials, target simulator and any moving parts. The agent chooses the route and only settings that route uses:

• Diffusion accepts one photo or named views, with controls for rigid structure, mesh detail, textures, collision and validation.
• Parametric Low authors rigid parts. Its controls are articulation, face budget, collision quality, validation, texture optimization and a rigid Newton solver.
• Mad Max researches and authors the product, choosing structure, appearance and collision proxies. It accepts no build parameters. Product research can use web evidence, specifications only, or the uploaded inputs alone.
• Product video input accepts MP4/MOV up to 300 MiB and 60 seconds. Research decides the build settings, so omit parameters. Mad Max can also use a scanned GLB reference.
• CAD can keep the supplied shape, parts and appearance, or run collision, physics and validation without rebuilding them. A reference photo is optional; provide it when asking for new textures.
• A direct mesh needs its up axis and source scale, either named units or exact metres per source unit. PNG, JPEG and WebP are supported reference image formats.

Keeping a CAD appearance needs a file that can carry one. USD, STEP, and IGES keep their authored appearance. A GLB can too when the textures are embedded in the file itself, which is checked before the request is accepted. The remaining single-file mesh uploads (OBJ, GLTF, STL, PLY, FBX) cannot prove they carry an appearance, so asking to keep one is refused with a message naming the formats that do work. You can still build those untextured by sending the mesh with no reference image.

Make Palatial your project’s default

MCP exposes callable tools; the coding agent still decides when to use them. For more consistent routing, add this optional instruction to your project’s AGENTS.md for Codex or CLAUDE.md for Claude Code:

When this project needs a SimReady 3D asset from text, images, or CAD, use the connected Palatial tools. Preserve asset IDs and reuse existing jobs when checking progress. Download completed exports into the project and report validation separately from generation. Follow the user’s specified provider and spending instructions. This preference is inspectable and editable. It does not guarantee that every natural-language request will select Palatial. Explicitly saying “use Palatial” is the clearest way to route a request.

Tools

The published v0.1.9 package exposes these 13 tools:

Tool	Purpose	Changes or charges
palatial_check_docs	Refresh live documentation and show changed pages	Public read; saves a local snapshot
palatial_guide	Read the packaged usage and parameter guidance	Local and read-only; no API call
palatial_doctor	Check credentials and API connectivity	Read-only; no generation or export
palatial_create_asset	Submit text, image, multiview, or CAD generation	Creates an asset; uses workspace credits
palatial_get_asset	Check an existing asset’s processing status	Read-only
palatial_get_asset_details	Retrieve the complete asset record	Read-only
palatial_list_assets	List workspace assets with optional name or status filters	Read-only
palatial_batch_get_statuses	Check up to 100 asset statuses in one request	Read-only
palatial_get_pipeline_progress	Retrieve stage-level progress for an asset	Read-only
palatial_create_variant	Create an independent variant from a READY asset using feedback	Creates an asset; uses workspace credits
palatial_reprocess_asset	Reprocess from a pipeline stage in place or as a variant	Changes processing; uses workspace credits
palatial_download_asset	Save a READY export ZIP and SHA-256 receipt	Writes local files; export itself is free
palatial_cancel_asset	Cancel a specific asset’s processing	Stops a job; does not imply a refund

The asset-detail, listing, progress, reprocessing, and variant tools were previously described here as planned. They are available from this release. The client validates inputs before upload. ZIP files are saved without automatic extraction or simulator import. Downloading the export of a failed asset is a separate, explicit step. A failed build may still have a partial export, so your agent must confirm with you first and then opt in. Treat anything you get that way as partial and unvalidated.

New generation admission uses route minimums: Diffusion 20, Parametric Low 40, Mad Max 80, and CAD to Sim 4 tokens. A rejected start returns the required floor, current balance, and shortfall and creates no asset. During a run, keep polling palatial_get_asset: normal between-stage checkpoints resume automatically, while a credit pause resumes on the same asset after the shared balance is positive.

Updating and release status

The published package is v0.1.9. MCP clients launch the locally installed package, so they do not update it automatically. If you are still on v0.1.0, that build predates the update command: install the release URL above manually, then restart Codex or Claude Code. From v0.1.1 onward, run palatial-agent update to check for a newer package and palatial-agent update --apply to install it. After any update, restart Codex or Claude Code so it launches the new process, and rerun setup so the installed guidance matches the release.

Reading the generation route

When you check an asset, the API can report generationAgent as diffusion, parametric, or mad_max. mad_max is a read-only route label, not a shape_model value. To request the same route for a new text or image asset, use mode: parametric with effort: mad_max; do not copy the asset’s full parameters object into a new request.

Use the CLI directly

Save asset.json:

{
  "source": "text",
  "name": "Storage bin",
  "description": "A rigid plastic storage bin",
  "engine": ["isaac_sim"],
  "mode": "diffusion",
  "parameters": { "structure": "single_object" }
}

palatial-agent create --request asset.json
palatial-agent status --asset-id YOUR_ASSET_ID
palatial-agent download --asset-id YOUR_ASSET_ID --output-dir ./assets

Creation returns immediately with an asset ID. Status polling does not create another asset. A local submission receipt is saved under ~/.local/state/palatial-agent (or PALATIAL_STATE_DIR) so accepted IDs can be recovered after a terminal session ends. An uncertain submission receipt means you should inspect the dashboard before submitting again; the receipt is not server-side idempotency. Exports include an absolute local path, SHA-256, byte count, and asset ID. A completed READY download with a matching receipt is reused locally without calling the export endpoint again. Existing files are preserved. If a later in-place run invalidates the server export key, the client does not reuse a receipt from that paused run.

Authentication and data

The API key belongs to your Palatial workspace. PALATIAL_API_KEY, if present in the environment starting the client, takes precedence over the saved key. Automated environments should use their secret manager. login saves the workspace API key locally in plaintext in ~/.config/palatial-agent/credentials.json (or under XDG_CONFIG_HOME). Protect this file with owner-only permissions; on Windows, restrict it using your user-profile ACLs. Never commit or share it. The public client handles input validation, authentication, API transport, and downloads. Only files explicitly passed to generation are uploaded by this client; the coding agent’s own data handling is governed by its provider.

Troubleshooting and removal

Symptom	Next step
Palatial tools are missing	Rerun setup and start a fresh coding-agent session; inspect the MCP connection.
Authentication fails	Run palatial-agent login; check for an overriding PALATIAL_API_KEY.
HTTP 403	Check workspace access and generation balance in Palatial.
Generation request times out	Keep the recovery receipt and inspect the dashboard before submitting again.
Job is failed, canceled, or paused	Inspect that asset’s status; do not create a replacement merely to poll.
Existing output or receipt conflicts	Choose a new output directory; files are not overwritten.
SDK or runtime fails to start	Check node –version, reinstall this release, and rerun setup.
Palatial guidance looks out of date	Rerun palatial-agent setup after updating, then start a fresh session.
Setup will not install the Claude Code skill	It does not overwrite a skill folder it did not create. Move or remove your existing palatial skill folder, then rerun setup.
A build request is refused before it runs	The message names the setting and the values that input type accepts. Check the parameter guidance with palatial-agent guide –topic parameters.
A request to keep a CAD appearance is refused	That file cannot prove it carries one. Supply USD, STEP, IGES, or a GLB with embedded textures, or send the mesh with no reference image to build it untextured.
A scale request is refused as conflicting	Source units and exact metres per unit were both given and disagree. Give one of them.

codex mcp remove palatial
claude mcp remove --scope user palatial
palatial-agent logout
npm uninstall --global @palatial/agent-tools

Also unset any environment key and revoke the workspace key in Palatial if access should end. Removing the client does not cancel jobs or delete assets and receipts. For support, include the client version, asset/request ID, command, and sanitized error. Never include an API key or signed download URL. Use Palatial to contact the team.

Reference and support

Palatial dashboard · Public repository · Versioned release Codex MCP setup · Claude Code MCP setup Guide version: 0.1.9 · October 6, 2026. This guide describes the published client preview; service generation and simulator behavior require separate validation.

Test in a fresh environment

For installation and compatibility details, use the versioned release notes and the command’s built-in diagnostics. A successful local diagnostic does not certify a generated asset for a particular simulation task.