Architecture

Overview

Cesium MCP consists of three independent packages that form a complete pipeline from AI agent to 3D globe:

AI Agent

Claude, Cursor, VS Code…

stdio / MCP

cesium-mcp-runtime

Node.js MCP Server

WebSocket

cesium-mcp-bridge

Browser SDK

API

CesiumJS Viewer

3D Globe

Package Roles

cesium-mcp-bridge (Browser)

The bridge runs inside the browser alongside your CesiumJS application. It:

• Connects to the runtime via WebSocket
• Receives JSON-RPC commands
• Executes CesiumJS API calls (camera, layers, entities, etc.)
• Returns results back through the WebSocket

Two calling styles:

• Type-safe methods: bridge.flyTo({ longitude: 2.29, latitude: 48.86, height: 1000 })
• JSON command dispatch: bridge.execute({ action: 'flyTo', params: { ... } })

cesium-mcp-runtime (Node.js)

The runtime is a Node.js MCP server that acts as a translator between the AI agent and the browser. It:

• Exposes 58 MCP tools (organized into 12 toolsets) + 2 resources via stdio
• Runs a WebSocket + HTTP server (default port 9100)
• Translates MCP tool calls into bridge commands
• Supports multi-session routing for multiple browser tabs
• Provides HTTP Push API (POST /api/command) for backend integration

cesium-mcp-dev (Node.js)

The dev server is a standalone IDE assistant that doesn't require a running globe. It provides:

• CesiumJS API documentation lookup (12 core classes)
• Code snippet generation for common patterns
• Entity template builder for generating configurations

Data Flow

AI Agent → Globe (Tool Call)

1. User: "Add a GeoJSON layer of earthquake data"
2. AI Agent → MCP tool call: addGeoJsonLayer({ url: "...", name: "earthquakes" })
3. Runtime receives tool call via stdio
4. Runtime sends WebSocket command: { action: "addGeoJsonLayer", params: { ... } }
5. Bridge executes: viewer.dataSources.add(Cesium.GeoJsonDataSource.load(...))
6. Bridge returns: { success: true, layerId: "..." }
7. Result flows back: Bridge → Runtime → AI Agent
8. AI Agent: "I've added the earthquake data layer to the map."

Globe → AI Agent (Resource Read)

1. AI Agent reads resource: cesium://scene/camera
2. Runtime forwards request to bridge via WebSocket
3. Bridge reads: viewer.camera.positionCartographic
4. Bridge returns: { longitude: 2.29, latitude: 48.86, height: 1000 }
5. AI Agent receives camera state for context-aware decisions

Toolsets & Dynamic Discovery

58 tools are organized into 12 toolsets to manage LLM tool selection complexity:

Toolset	Tools	Default
view	7	Yes
entity	9	Yes
layer	6	Yes
interaction	2	Yes
camera	4	—
entity-ext	7	—
animation	8	—
tiles	3	—
trajectory	1	—
heatmap	1	—
geolocation	1	—

By default, 4 core toolsets (~24 tools) are enabled. The remaining toolsets can be activated via:

1. Environment variable: CESIUM_TOOLSETS=all enables everything
2. Dynamic Discovery: Two meta-tools (list_toolsets, enable_toolset) allow the AI agent to discover and activate toolsets at runtime — no user configuration needed

AI: "I need to create an animation"
→ calls list_toolsets → sees animation toolset is disabled
→ calls enable_toolset("animation") → 8 animation tools become available
→ calls createAnimation(...)

Session Routing

Multiple browser tabs can connect to the same runtime. Each connection uses a sessionId:

Browser Tab 1 (sessionId: "project-a") ──┐
                                         ├── cesium-mcp-runtime ── AI Agent
Browser Tab 2 (sessionId: "project-b") ──┘

For MCP HTTP mode, add ?session=xxx to the endpoint URL to automatically route all tool calls to the specified browser:

http://localhost:3216/mcp?session=project-a

Routing priority: tool param sessionId > URL ?session=xxx > DEFAULT_SESSION_ID env > first connected browser.

Version Strategy

All three packages share the same version number using changesets with fixed versioning mode.

Major.minor tracks CesiumJS:

• cesium-mcp-*@1.139.x targets cesium@~1.139.0

Patch versions iterate independently for MCP feature updates.