MCP Server

SpAItial hosts a remote Model Context Protocol (MCP) server so AI agents — Cursor, Claude, VS Code, Cline, and anything else that speaks MCP — can generate and manage 3D worlds directly, without you writing any API glue.

https://mcp.spaitial.ai/mcp

It's a stateless, streamable-HTTP server. Every tool maps 1:1 onto the Developer API, so an agent can prompt → generate → poll → download a splat or mesh entirely on its own.

Discovery

Agents that support MCP Server Cards can discover the hosted server from:

https://mcp.spaitial.ai/.well-known/mcp/server-card.json

The card advertises the streamable-HTTP endpoint, auth schemes, and supported MCP surfaces. A compatibility alias is also available at https://mcp.spaitial.ai/.well-known/mcp.json.

Bring your own key (BYOK)

The server holds no credentials. Each request must carry your Spaitial API key, and generations are billed to your account. Get a key at developers.spaitial.ai, then send it as the X-Spaitial-Api-Key header (or Authorization: Bearer spt_...). Requests without a key return 401.

Install

Pick your agent below. Everywhere you see spt_live_YOUR_KEY, replace it with your real key. The server accepts the key as either X-Spaitial-Api-Key: <key> or Authorization: Bearer <key>.

Cursor

Clicking the badge opens Cursor and pre-fills the server. After it's added, open Settings → MCP, edit the spaitial server, and replace the placeholder key with your own.

VS Code

The badge opens a vscode.dev page that redirects to the VS Code desktop app — approve the "Open Visual Studio Code?" browser prompt. If the page just sits there (no desktop app registered, or the prompt was blocked), use the CLI instead — it always works:

code --add-mcp '{"name":"spaitial","type":"http","url":"https://mcp.spaitial.ai/mcp","headers":{"X-Spaitial-Api-Key":"spt_live_YOUR_KEY"}}'

Then open the spaitial server via MCP: Open User Configuration and set your real key.

Claude Code

Add the remote server with one command:

claude mcp add --transport http spaitial https://mcp.spaitial.ai/mcp \
  --header "X-Spaitial-Api-Key: spt_live_YOUR_KEY"

Use --scope user to make it available across all projects, or --scope project to commit it to a shared .mcp.json. Verify with claude mcp list.

Codex

Codex configures remote (streamable-HTTP) servers in ~/.codex/config.toml. Add:

[mcp_servers.spaitial]
url = "https://mcp.spaitial.ai/mcp"
http_headers = { "X-Spaitial-Api-Key" = "spt_live_YOUR_KEY" }

To avoid committing the key, pull it from the environment instead:

[mcp_servers.spaitial]
url = "https://mcp.spaitial.ai/mcp"
env_http_headers = { "X-Spaitial-Api-Key" = "SPAITIAL_API_KEY" }

Then set SPAITIAL_API_KEY=spt_live_... in your shell. Run /mcp in the Codex TUI to confirm it's active.

opencode

Add a remote entry to your opencode.json (or ~/.config/opencode/opencode.json). oauth: false tells opencode to use the API key instead of attempting an OAuth flow:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spaitial": {
      "type": "remote",
      "url": "https://mcp.spaitial.ai/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "X-Spaitial-Api-Key": "{env:SPAITIAL_API_KEY}" }
    }
  }
}

{env:SPAITIAL_API_KEY} reads the key from your environment; swap in the literal spt_live_... if you prefer.

Claude Desktop / other

Clients with native remote-MCP + header support: point them at https://mcp.spaitial.ai/mcp and send X-Spaitial-Api-Key: spt_live_YOUR_KEY.

For clients that only support local (stdio) servers — including Claude Desktop — bridge to the remote URL with mcp-remote:

{
  "mcpServers": {
    "spaitial": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.spaitial.ai/mcp",
        "--header",
        "X-Spaitial-Api-Key:${SPAITIAL_API_KEY}"
      ],
      "env": { "SPAITIAL_API_KEY": "spt_live_YOUR_KEY" }
    }
  }
}

Keep your key out of shared config

Where a client supports it (Codex env_http_headers, opencode {env:...}, mcp-remote's ${SPAITIAL_API_KEY} + env block), read the key from an environment variable instead of hardcoding it — especially for any config you commit or share.

Tools

Tool	Maps to
list_models	GET /v1/models
create_world	POST /v1/worlds — text / image URL / base64 / file_id / panorama_id, is_pano, output_format, visibility, webhook, idempotency
edit_panorama	POST /v1/panoramas/edit — edit a completed API-created world/request, or iterate on a pano_..., with an optional reference image set
list_panoramas	GET /v1/panoramas
get_panorama	GET /v1/panoramas/:id
get_edited_panorama_download_url	GET /v1/panoramas/:id/download (resolved signed URL)
get_world_status	GET /v1/worlds/requests/:id/status
get_world	GET /v1/worlds/requests/:id
list_world_requests	GET /v1/worlds/requests
get_splat_download_url	GET /v1/worlds/requests/:id/splat (resolved signed URL)
get_panorama_download_url	GET /v1/worlds/requests/:id/panorama (resolved signed URL)
update_world	PATCH /v1/worlds/requests/:id
cancel_world	POST /v1/worlds/requests/:id/cancel
start_mesh_export	POST /v1/worlds/requests/:id/exports/:type
get_mesh_export	GET /v1/worlds/requests/:id/exports/:type

Each tool returns the same JSON shapes documented in the API reference, including the standard error envelope.

Example prompts

Once installed, just ask your agent in natural language:

• "Generate a Spaitial world of an empty cozy reading nook and give me the splat download URL when it's done."
• "Edit world <world-id>: change the rug to yellow, then show me the edited panorama."
• "Add this attached sofa to pano_..., then create a new world from the result."
• "List my recent world generations and their statuses."
• "Export a simplified collision mesh for request req_... and download it when ready."

The agent calls create_world, polls get_world_status, then get_splat_download_url / start_mesh_export — the same flow you'd script against the REST API, driven by the model.

For app-style edits, the agent calls edit_panorama, lets you inspect the returned pano_... with get_edited_panorama_download_url, optionally iterates by passing that pano_... back to edit_panorama, then calls create_world with panorama_id when you're satisfied.

Notes

• Authentication is identical to the REST API — the same spt_live_ / spt_test_ keys and scopes apply per tool.
• Generation time is ~5–10 minutes (Echo 2 - Standard); agents should poll get_world_status rather than block.
• Panorama edits are synchronous and return a pano_... artifact. There is no aspect-ratio option; edited panoramas stay valid for world generation.
• Downloads return short-lived signed URLs (~5 min); resolve them just before fetching.
• Prefer scripting instead? See the LLM Skills page for a self-contained REST reference, or install the skill with npx skills add spaitial-dev/spaitial-api-skill.