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.

Visibility scope: connector vs. web app

list_world_requests (and the individual get_world* lookups) only see worlds generated through the API/connector with your API key. Worlds you create in the Spaitial web app (dashboard) are not listed by the connector — even when the API key belongs to the same account.

For an automation or agent flow, generate through the connector (create_world) so the pipeline can read the result back. If you kick off generation in the web app, the connector won't be able to discover or download that world.

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.