Architecture

Overview

Cesium MCP uses shared contracts and a protocol-neutral browser executor with separate adapters for WebMCP, MCP clients, and IDE assistance. The diagram below shows the MCP runtime path:

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-contracts (Shared)

The contracts package owns transport-neutral tool names, descriptions, JSON Schemas, defaults, result shapes, and toolset membership. The WebMCP adapter and MCP runtime both consume these definitions. At registration time the runtime converts the canonical JSON Schema to Zod, so MCP validation and WebMCP declarations cannot drift into separate schemas.

cesium-mcp-bridge (Browser)

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

• Executes commands received from WebMCP, function calling, or the MCP runtime
• Can connect to the runtime via WebSocket when that integration path is used
• Executes CesiumJS API calls (camera, layers, entities, etc.)
• Returns structured results to the calling adapter

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-webmcp (Browser Adapter)

The WebMCP package registers the shared contracts on the native document.modelContext API. It exposes 15 core tools by default or all 61 browser-safe tools across 12 toolsets. It does not include an AI model, chat UI, MCP server, WebSocket transport, or polyfill.

This adapter is intentionally separate from cesium-mcp-runtime; see the WebMCP integration guide.

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 62 MCP command 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

62 Runtime command 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

The established cesium-mcp-bridge, cesium-mcp-runtime, and cesium-mcp-dev packages share a version number using changesets with fixed versioning mode. The newer cesium-mcp-contracts and cesium-mcp-webmcp packages use independent semantic versions.

Major.minor tracks CesiumJS:

• cesium-mcp-*@1.143.x targets the verified cesium@~1.143.0 baseline

Patch versions iterate independently for MCP feature updates.