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.

Codex CLI or Claude Code calls the local Palatial MCP client, which calls the Palatial API with a workspace key. The API handles generation and returns status and exports, and the client saves asset files in the project.

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.0/palatial-agent-tools-0.1.0.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 the registration commands with –dry-run. Setup adds a server named palatial in the user’s client configuration. Review or remove an existing server of that name first. 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.

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. The CAD source units are millimetres and its up axis is Z. Target Isaac Sim and keep the export in ./assets/gripper. Specify the target simulator, dimensions or source units, and articulation requirements when known. 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.

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 currently published v0.1.0 package exposes these five tools:

Tool	Purpose	Changes or charges
`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_download_asset`	Save a READY export ZIP and SHA-256 receipt	Writes local files; export may consume a credit
`palatial_cancel_asset`	Cancel a specific asset’s processing	Stops a job; does not imply a refund

The client validates inputs before upload. ZIP files are saved without automatic extraction or simulator import. The repository’s main branch contains additional asset-detail, listing, progress, reprocessing, and variant tools that are planned for a future package release; they are not available from the published v0.1.0 tarball.

Updating and release status

The published package is v0.1.0. MCP clients launch the locally installed package, so they do not update it automatically. The published v0.1.0 package predates the update command. To move from v0.1.0 to a later release, install that release URL manually from GitHub, then restart Codex or Claude Code. Releases that include the updater can subsequently run palatial-agent update to check and palatial-agent update --apply to install a newer package.

Use the CLI directly

Save asset.json:

{
  "source": "text",
  "name": "Storage bin",
  "description": "A rigid plastic storage bin",
  "engine": ["isaac_sim"],
  "enable_parts_segmentation": false
}

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 download with a matching receipt is reused locally without calling the export endpoint again. Existing files are preserved. If a download fails after export authorization, a credit may already have been consumed; the client does not automatically retry that export.

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.

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.0 · September 8, 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.