cesium-mcp-runtime

MCP Server (stdio) — 62 command tools (12 toolsets) + 2 resources, with dynamic discovery.

Release channels

• Stable: npx -y cesium-mcp-runtime → npm latest

The stable release supports MCP 2025-11-25 and 2026-07-28, uses the stable TypeScript SDK v2, and passes the official server-stateless conformance scenario (28/28).

Installation & Run

npx -y cesium-mcp-runtime

Open http://localhost:9100/ for the included Viewer. The default path does not require a separate Bridge package.

Or install globally:

npm install -g cesium-mcp-runtime
cesium-mcp-runtime

MCP Client Configuration

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "cesium": {
      "command": "npx",
      "args": ["-y", "cesium-mcp-runtime"]
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "cesium-mcp": {
      "command": "npx",
      "args": ["-y", "cesium-mcp-runtime"]
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "cesium": {
      "command": "npx",
      "args": ["-y", "cesium-mcp-runtime"]
    }
  }
}

MCP Tools (62 command tools + 2 discovery meta-tools)

Tools are organized into 12 toolsets. By default, 4 core toolsets are enabled (30 tools). Set CESIUM_TOOLSETS=all for everything, or let the AI discover and activate toolsets dynamically. Shared titles, behavior annotations, localized descriptions, defaults, input validation, advertised output schemas, and structured results come from the canonical JSON Schemas in cesium-mcp-contracts. Tool calls retain text content for older clients.

The Runtime npm artifact includes the browser Bridge bundle served by /bridge.js. The built-in Viewer does not depend on an unpkg fallback, while CesiumJS assets continue to load from the official Cesium CDN.

The default MCP path therefore needs only cesium-mcp-runtime. A separate cesium-mcp-bridge installation is for custom CesiumJS pages, not built-in Viewer users.

Toolsets

Toolset	Tools	Default	Description
view	8	Yes	Camera view controls + viewpoint bookmarks + scene export
entity	10	Yes	Core entity operations + batch, query & property inspection
layer	9	Yes	Layer management (GeoJSON, schema, style, basemap)
interaction	3	Yes	Screenshot, highlight & measurement
camera	4	—	Advanced camera controls (orbit, lookAt)
entity-ext	7	—	Extended entity types (box, cylinder, wall, etc.)
animation	8	—	Animation system (waypoints, clock, tracking, lighting)
tiles	7	—	3D Tiles, Gaussian Splats, terrain, imagery services, CZML & KML
trajectory	1	—	Trajectory playback
heatmap	1	—	Heatmap visualization
scene	3	—	Scene options, post-processing & Runtime-only Ion credentials
geolocation	1	—	Geocoding — convert address/place name to coordinates (Nominatim/OSM)

Dynamic Discovery

When not in all mode, two meta-tools are always available:

Tool	Description
list_toolsets	List all toolset groups with enabled status
enable_toolset	Dynamically enable a toolset at runtime

View

flyTo

Animate camera to a position with smooth transition.

Parameter	Type	Required	Default	Description
longitude	number	✅	—	Longitude (-180 to 180)
latitude	number	✅	—	Latitude (-90 to 90)
height	number	—	50000	Camera height in meters
heading	number	—	0	Heading in degrees, 0 = North
pitch	number	—	-45	Pitch in degrees, -90 = straight down
duration	number	—	2	Flight animation duration in seconds

setView

Instantly set camera position and orientation (no animation).

Parameter	Type	Required	Default	Description
longitude	number	✅	—	Longitude (-180 to 180)
latitude	number	✅	—	Latitude (-90 to 90)
height	number	—	50000	Height in meters
heading	number	—	0	Heading in degrees
pitch	number	—	-90	Pitch in degrees
roll	number	—	0	Roll in degrees

getView

Return current camera position and orientation. No parameters.

Returns: { longitude, latitude, height, heading, pitch, roll }

zoomToExtent

Fit view to a geographic bounding box.

Parameter	Type	Required	Default	Description
west	number	✅	—	West boundary longitude
south	number	✅	—	South boundary latitude
east	number	✅	—	East boundary longitude
north	number	✅	—	North boundary latitude
duration	number	—	2	Animation duration in seconds

saveViewpoint

Save the current camera state as a named viewpoint bookmark.

Parameter	Type	Required	Default	Description
name	string	✅	—	Viewpoint bookmark name

Returns: The saved ViewState object.

loadViewpoint

Restore a previously saved viewpoint bookmark.

Parameter	Type	Required	Default	Description
name	string	✅	—	Viewpoint bookmark name
duration	number	—	0	Flight duration in seconds (0 = instant)

Returns: The restored ViewState, or error if not found.

listViewpoints

List all saved viewpoint bookmarks. No parameters.

Returns: [{ name, state: ViewState }]

exportScene

Export all entities and layers in the current scene as a structured JSON snapshot.

No parameters.

Returns: { entities: [...], layers: [...], camera: ViewState }

Entity

addMarker

Add a point marker with optional label. Returns entityId.

Parameter	Type	Required	Default	Description
longitude	number	✅	—	Longitude (-180 to 180)
latitude	number	✅	—	Latitude (-90 to 90)
label	string	—	—	Label text
color	string	—	"#3B82F6"	CSS color
size	number	—	12	Point size in pixels
id	string	—	auto	Custom layer ID

addLabel

Add text labels to GeoJSON features (display attribute values).

Parameter	Type	Required	Default	Description
data	object	✅	—	GeoJSON FeatureCollection
field	string	✅	—	Property field name for label text
style	object	—	—	Label style (font, fillColor, outlineColor, scale)

addModel

Place a 3D model (glTF/GLB) at a position. Returns entityId.

Parameter	Type	Required	Default	Description
longitude	number	✅	—	Longitude (-180 to 180)
latitude	number	✅	—	Latitude (-90 to 90)
height	number	—	0	Height in meters
url	string	✅	—	glTF/GLB model URL
scale	number	—	1	Scale factor
heading	number	—	0	Heading in degrees
pitch	number	—	0	Pitch in degrees
roll	number	—	0	Roll in degrees
label	string	—	—	Model label text

addPolygon

Add a polygon area with fill and outline. Returns entityId.

Parameter	Type	Required	Default	Description
coordinates	number[][]	✅	—	Ring coordinates [[lon, lat, height?], ...]
color	string	—	"#3B82F6"	Fill color (CSS)
outlineColor	string	—	"#FFFFFF"	Outline color
opacity	number	—	0.6	Fill opacity (0–1)
extrudedHeight	number	—	—	Extrusion height in meters
clampToGround	boolean	—	true	Clamp to terrain
label	string	—	—	Polygon label text

addPolyline

Add a polyline (path/route). Returns entityId.

Parameter	Type	Required	Default	Description
coordinates	number[][]	✅	—	Coordinates [[lon, lat, height?], ...]
color	string	—	"#3B82F6"	Line color (CSS)
width	number	—	3	Line width in pixels
clampToGround	boolean	—	true	Clamp to terrain
label	string	—	—	Polyline label text

updateEntity

Update properties of an existing entity.

Parameter	Type	Required	Default	Description
entityId	string	✅	—	Entity ID to update
position	object	—	—	New position { longitude, latitude, height? }
label	string	—	—	New label text
color	string	—	—	New color (CSS)
scale	number	—	—	New scale factor
show	boolean	—	—	Visibility

removeEntity

Remove a single entity by ID.

Parameter	Type	Required	Default	Description
entityId	string	✅	—	Entity ID to remove

batchAddEntities

Add multiple entities of different types in a single call.

Parameter	Type	Required	Default	Description
entities	object[]	✅	—	Array of entity definitions

Each entity object must include a type field ("marker", "polyline", "polygon", "model", "label", "billboard", "box", "cylinder", "ellipse", "rectangle", "wall", "corridor") plus the corresponding parameters for that entity type.

Returns: { entityIds: string[], errors: string[] }

queryEntities

Search and filter entities in the scene.

Parameter	Type	Required	Default	Description
name	string	—	—	Filter by name (fuzzy match, case-insensitive)
type	string	—	—	Filter by type ("point", "billboard", "label", "model", "polyline", "polygon")
bbox	number[]	—	—	Bounding box filter [west, south, east, north]

Returns: [{ entityId, name?, type, position? }]

getEntityProperties

Get all properties of a specific entity by ID.

Parameter	Type	Required	Default	Description
entityId	string	✅	—	Entity ID

Returns: { entityId, name, type, position?, properties }

Layer

addGeoJsonLayer

Load GeoJSON data as a layer with optional styling. Supports both inline data and URL loading.

Parameter	Type	Required	Default	Description
data	object	—	—	GeoJSON FeatureCollection (inline data)
url	string	—	—	URL to fetch GeoJSON from (browser-side fetch)
id	string	—	auto	Layer ID
name	string	—	—	Display name
style	object	—	—	Style config (color, opacity, pointSize, strokeWidth, randomColor, gradient, choropleth, category)

Either data or url must be provided.

listLayers

List all currently loaded layers. No parameters.

Returns: [{ id, name, type, visible, color }]

removeLayer

Remove a layer by ID.

Parameter	Type	Required	Default	Description
id	string	✅	—	Layer ID (from listLayers)

clearAll

Remove all layers, entities, and data sources. No parameters.

setLayerVisibility

Toggle layer visibility.

Parameter	Type	Required	Default	Description
id	string	✅	—	Layer ID
visible	boolean	✅	—	Whether layer is visible

updateLayerStyle

Modify layer styling properties.

Parameter	Type	Required	Default	Description
layerId	string	✅	—	Layer ID
labelStyle	object	—	—	Label style (font, fillColor, outlineColor, outlineWidth, scale)
layerStyle	object	—	—	Entity layer style (color, opacity, strokeWidth, pointSize; GeoJSON thematic styles: choropleth/category/randomColor/gradient, mutually exclusive)
imageryStyle	object	—	—	Imagery visual style (alpha, brightness, contrast, hue, saturation, gamma); use setLayerVisibility for visibility
primitiveStyle	object	—	—	GeoJSON Primitive material style (color, opacity, outlineColor, outlineWidth, pointSize, lineWidth)
tileStyle	object	—	—	3D Tiles style (Cesium3DTileStyle expressions: color, show, pointSize, meta)

getLayerSchema

Get the property field structure of a layer (GeoJSON DataSource or 3D Tiles batch table).

Parameter	Type	Required	Default	Description
layerId	string	✅	—	Layer ID

Returns: { layerId, layerName, entityCount, fields: [{ name, type, sample? }] }

setBasemap

Switch the base imagery layer.

Parameter	Type	Required	Default	Description
basemap	string	✅	—	"dark" | "satellite" | "standard"

Camera

lookAtTransform

Orbit-style camera aim at a target position.

Parameter	Type	Required	Default	Description
longitude	number	✅	—	Target longitude
latitude	number	✅	—	Target latitude
height	number	—	0	Target height in meters
heading	number	—	0	Camera heading in degrees
pitch	number	—	-45	Camera pitch in degrees
range	number	—	1000	Distance from target in meters

startOrbit

Start orbiting the camera around the current view center.

Parameter	Type	Required	Default	Description
speed	number	—	0.005	Rotation speed (radians/tick)
clockwise	boolean	—	true	Orbit direction

stopOrbit

Stop the camera orbit animation. No parameters.

setCameraOptions

Configure camera controller options.

Parameter	Type	Required	Default	Description
enableRotate	boolean	—	—	Enable rotation
enableTranslate	boolean	—	—	Enable translation
enableZoom	boolean	—	—	Enable zoom
enableTilt	boolean	—	—	Enable tilt
enableLook	boolean	—	—	Enable look
minimumZoomDistance	number	—	—	Min zoom distance (meters)
maximumZoomDistance	number	—	—	Max zoom distance (meters)
enableInputs	boolean	—	—	Enable/disable all inputs

Extended Entity Types

addBillboard

Add an image icon at a position.

Parameter	Type	Required	Default	Description
longitude	number	✅	—	Longitude
latitude	number	✅	—	Latitude
height	number	—	0	Height in meters
image	string	✅	—	Image URL
name	string	—	—	Billboard name
scale	number	—	1.0	Scale factor
color	ColorInput	—	—	Tint color
pixelOffset	{x, y}	—	—	Pixel offset
heightReference	string	—	—	"NONE" | "CLAMP_TO_GROUND" | "RELATIVE_TO_GROUND"

addBox

Add a 3D box entity.

Parameter	Type	Required	Default	Description
longitude	number	✅	—	Longitude
latitude	number	✅	—	Latitude
height	number	—	0	Height in meters
dimensions	object	✅	—	{ width, length, height } in meters
name	string	—	—	Box name
material	MaterialInput	—	—	Material (color, image, etc.)
outline	boolean	—	true	Show outline
outlineColor	ColorInput	—	—	Outline color
fill	boolean	—	true	Show fill
orientation	object	—	—	{ heading, pitch, roll } in degrees

addCorridor

Add a corridor (path with width).

Parameter	Type	Required	Default	Description
positions	PositionDegrees[]	✅	—	Array of { longitude, latitude, height? }
width	number	✅	—	Width in meters
name	string	—	—	Corridor name
material	MaterialInput	—	—	Material
cornerType	string	—	—	"ROUNDED" | "MITERED" | "BEVELED"
height	number	—	—	Height above ground
extrudedHeight	number	—	—	Extruded height
outline	boolean	—	—	Show outline

addCylinder

Add a cylinder or cone.

Parameter	Type	Required	Default	Description
longitude	number	✅	—	Longitude
latitude	number	✅	—	Latitude
height	number	—	0	Height in meters
length	number	✅	—	Cylinder height in meters
topRadius	number	✅	—	Top radius in meters
bottomRadius	number	✅	—	Bottom radius in meters
name	string	—	—	Name
material	MaterialInput	—	—	Material
outline	boolean	—	true	Show outline
slices	number	—	128	Number of slices

addEllipse

Add an ellipse (oval).

Parameter	Type	Required	Default	Description
longitude	number	✅	—	Center longitude
latitude	number	✅	—	Center latitude
height	number	—	0	Height in meters
semiMajorAxis	number	✅	—	Semi-major axis in meters
semiMinorAxis	number	✅	—	Semi-minor axis in meters
name	string	—	—	Name
material	MaterialInput	—	—	Material
extrudedHeight	number	—	—	Extruded height
rotation	number	—	—	Rotation in radians
outline	boolean	—	—	Show outline

addRectangle

Add a rectangle by geographic bounds.

Parameter	Type	Required	Default	Description
west	number	✅	—	West longitude
south	number	✅	—	South latitude
east	number	✅	—	East longitude
north	number	✅	—	North latitude
name	string	—	—	Name
material	MaterialInput	—	—	Material
height	number	—	—	Height
extrudedHeight	number	—	—	Extruded height
outline	boolean	—	—	Show outline

addWall

Add a wall along positions.

Parameter	Type	Required	Default	Description
positions	PositionDegrees[]	✅	—	Array of { longitude, latitude, height? }
name	string	—	—	Name
minimumHeights	number[]	—	—	Min heights at each position
maximumHeights	number[]	—	—	Max heights at each position
material	MaterialInput	—	—	Material
outline	boolean	—	—	Show outline

Animation

createAnimation

Create a time-based animation with waypoints (moving entity along a path).

Parameter	Type	Required	Default	Description
waypoints	object[]	✅	—	[{ longitude, latitude, height?, time }] — time is ISO 8601
name	string	—	—	Animation name
modelUri	string	—	—	glTF URL or preset: cesium_man, cesium_air, ground_vehicle, cesium_drone
showPath	boolean	—	true	Show trail path
pathWidth	number	—	2	Path width in pixels
pathColor	string	—	"#00FF00"	Path color (CSS)
pathLeadTime	number	—	0	Path lead time in seconds
pathTrailTime	number	—	1e10	Path trail time in seconds
multiplier	number	—	1	Clock speed multiplier
shouldAnimate	boolean	—	true	Auto-start animation

controlAnimation

Play or pause the current animation.

Parameter	Type	Required	Default	Description
action	string	✅	—	"play" | "pause"

removeAnimation

Remove an animation entity.

Parameter	Type	Required	Default	Description
entityId	string	✅	—	Entity ID of animation to remove

listAnimations

List all active animations. No parameters.

Returns: [{ entityId, name?, startTime, stopTime, exists }]

updateAnimationPath

Update visual properties of an animation path.

Parameter	Type	Required	Default	Description
entityId	string	✅	—	Animation entity ID
width	number	—	—	Path width in pixels
color	string	—	—	Path color (CSS)
leadTime	number	—	—	Lead time in seconds
trailTime	number	—	—	Trail time in seconds
show	boolean	—	—	Show/hide path

trackEntity

Follow an entity with the camera, or stop tracking.

Parameter	Type	Required	Default	Description
entityId	string	—	—	Entity ID to track (omit to stop)
heading	number	—	—	Camera heading in degrees
pitch	number	—	-30	Camera pitch in degrees
range	number	—	500	Camera distance in meters

controlClock

Configure the Cesium clock.

Parameter	Type	Required	Default	Description
action	string	✅	—	"configure" | "setTime" | "setMultiplier"
startTime	string	—	—	ISO 8601 start time
stopTime	string	—	—	ISO 8601 stop time
currentTime	string	—	—	ISO 8601 current time
time	string	—	—	ISO 8601 time to jump to (for setTime)
multiplier	number	—	—	Clock speed multiplier
shouldAnimate	boolean	—	—	Whether clock should animate
clockRange	string	—	—	"UNBOUNDED" | "CLAMPED" | "LOOP_STOP"

setGlobeLighting

Enable/disable globe lighting and atmospheric effects.

Parameter	Type	Required	Default	Description
enableLighting	boolean	—	—	Enable globe lighting
dynamicAtmosphereLighting	boolean	—	—	Dynamic atmosphere lighting
dynamicAtmosphereLightingFromSun	boolean	—	—	Use sun position for atmosphere

3D Data

load3dTiles

Load a 3D Tileset (buildings, terrain mesh, etc.) from URL or Cesium Ion asset ID.

Parameter	Type	Required	Default	Description
url	string	—	—	URL to tileset.json
ionAssetId	number	—	—	Cesium Ion asset ID
id	string	—	auto	Layer ID
name	string	—	—	Display name
maximumScreenSpaceError	number	—	16	Max screen space error (lower = more detail)
heightOffset	number	—	—	Height offset in meters

Either url or ionAssetId must be provided.

loadTerrain

Set the terrain provider.

Parameter	Type	Required	Default	Description
provider	string	✅	—	"flat" | "arcgis" | "cesiumion"
url	string	—	—	Custom terrain service URL
cesiumIonAssetId	number	—	—	Cesium Ion asset ID (for cesiumion)

loadImageryService

Add an imagery layer from URL or Cesium Ion asset ID.

Parameter	Type	Required	Default	Description
url	string	—	—	Imagery service URL
serviceType	string	—	—	"wms" | "wmts" | "xyz" | "arcgis_mapserver" | "ion"
ionAssetId	number	—	—	Cesium Ion asset ID
id	string	—	auto	Layer ID
name	string	—	—	Display name
layerName	string	—	—	WMS/WMTS layer name
opacity	number	—	1.0	Opacity (0–1)

Either url + serviceType or ionAssetId must be provided.

loadCzml

Load CZML time-dynamic data source (inline data array or remote URL).

Parameter	Type	Required	Default	Description
data	unknown[]	—	—	CZML packet array (inline)
url	string	—	—	URL to CZML file
id	string	—	auto	Layer ID
name	string	—	—	Display name
sourceUri	string	—	—	Base URI for relative references
clampToGround	boolean	—	false	Clamp entities to ground

Either data or url must be provided.

loadKml

Load KML/KMZ data source (inline string or remote URL).

Parameter	Type	Required	Default	Description
data	string	—	—	KML document as string (inline)
url	string	—	—	URL to KML/KMZ file
id	string	—	auto	Layer ID
name	string	—	—	Display name
clampToGround	boolean	—	false	Clamp entities to ground

Either data or url must be provided.

Interaction

screenshot

Capture the current globe view as an image. No parameters.

Returns: Base64 PNG image (MCP image content type).

highlight

Highlight specific features in a layer.

Parameter	Type	Required	Default	Description
layerId	string	✅	—	Layer ID
featureIndex	number	—	—	Feature index (omit to highlight all)
color	string	—	"#FFFF00"	Highlight color (CSS)

measure

Measure distance or area between points on the globe.

Parameter	Type	Required	Default	Description
type	string	✅	—	"distance" | "area"
coordinates	number[][]	✅	—	Points [[lon, lat], ...] (2 for distance, 3+ for area)

Returns: { type, value, unit, coordinates }

Scene

setSceneOptions

Configure scene environment (fog, atmosphere, shadows, sun, moon, background color, depth testing).

Parameter	Type	Required	Default	Description
fogEnabled	boolean	—	—	Enable/disable fog
fogDensity	number	—	0.0002	Fog density (0.0–1.0)
fogMinimumBrightness	number	—	—	Minimum fog brightness (0.0–1.0)
skyAtmosphereShow	boolean	—	—	Show sky atmosphere
skyAtmosphereHueShift	number	—	—	Sky hue shift (-1.0–1.0)
skyAtmosphereSaturationShift	number	—	—	Sky saturation shift (-1.0–1.0)
skyAtmosphereBrightnessShift	number	—	—	Sky brightness shift (-1.0–1.0)
groundAtmosphereShow	boolean	—	—	Show ground atmosphere
shadowsEnabled	boolean	—	—	Enable shadows
shadowsSoftShadows	boolean	—	—	Use soft shadows
shadowsDarkness	number	—	—	Shadow darkness (0.0–1.0)
sunShow	boolean	—	—	Show the sun
sunGlowFactor	number	—	1.0	Sun glow factor
moonShow	boolean	—	—	Show the moon
depthTestAgainstTerrain	boolean	—	—	Depth test against terrain
backgroundColor	string	—	—	Background color (CSS format)

setPostProcess

Configure post-processing effects (bloom, SSAO, FXAA).

Parameter	Type	Required	Default	Description
bloom	boolean	—	—	Enable bloom glow effect
bloomContrast	number	—	128	Bloom contrast
bloomBrightness	number	—	-0.3	Bloom brightness
bloomDelta	number	—	1.0	Bloom delta
bloomSigma	number	—	3.78	Bloom sigma
bloomStepSize	number	—	5.0	Bloom step size
bloomGlowOnly	boolean	—	—	Show only the glow
ambientOcclusion	boolean	—	—	Enable ambient occlusion (SSAO)
aoIntensity	number	—	3.0	AO intensity
aoBias	number	—	0.1	AO bias
aoLengthCap	number	—	0.26	AO length cap
aoStepSize	number	—	1.95	AO step size
fxaa	boolean	—	—	Enable FXAA anti-aliasing

Other

playTrajectory trajectory

Animate an entity along a path over time.

Parameter	Type	Required	Default	Description
coordinates	number[][]	✅	—	Path coordinates [[lon, lat, alt?], ...]
id	string	—	auto	Trajectory layer ID
name	string	—	—	Trajectory name
durationSeconds	number	—	10	Animation duration in seconds
trailSeconds	number	—	2	Trail length in seconds
label	string	—	—	Moving entity label

addHeatmap heatmap

Create a heatmap overlay from point data.

Parameter	Type	Required	Default	Description
data	object	✅	—	GeoJSON Point FeatureCollection
radius	number	—	30	Heat influence radius in pixels

geocode geolocation

Convert an address, landmark, or place name to geographic coordinates (longitude/latitude). Uses OpenStreetMap Nominatim — no API key required. Supports HTTPS_PROXY / HTTP_PROXY / ALL_PROXY environment variables for proxy.

Parameter	Type	Required	Default	Description
address	string	✅	—	Address, landmark, or place name, e.g. "Eiffel Tower", "故宫"
countryCode	string	—	—	2-letter ISO country code to limit search scope (e.g. CN, US, JP)

Returns: { success, longitude, latitude, displayName, boundingBox }

MCP Resources (2)

URI	Description
cesium://scene/camera	Current camera state (position, orientation)
cesium://scene/layers	List of all loaded layers with metadata

Resources are read-only and can be polled by the AI agent for context-aware decisions.

Environment Variables

Variable	Default	Description
CESIUM_WS_PORT	9100	WebSocket server port for bridge connections
DEFAULT_SESSION_ID	default	Which browser session to route MCP calls to
CESIUM_TOOLSETS	(not set)	Toolset activation: omit for defaults, all for everything, or comma-separated list
OSM_USER_AGENT	cesium-mcp-runtime/1.0	User-Agent header for Nominatim geocode requests
CESIUM_LOCALE	en	Tool description language: en (English, default) or zh-CN (Chinese)

Session Routing

Multiple browser tabs can connect simultaneously. Each bridge instance registers with a sessionId:

Tab 1: sessionId = "project-a"
Tab 2: sessionId = "project-b"

Routing via MCP URL

Add ?session=xxx to the MCP HTTP endpoint URL to route all tool calls to a specific browser:

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

This is the recommended approach for third-party integrations (e.g., Dify) — no prompt injection or tool parameter needed.

Routing priority

1. sessionId in tool parameters (explicit per-call override)
2. ?session=xxx in MCP HTTP URL (connection-level)
3. DEFAULT_SESSION_ID environment variable
4. First connected browser (fallback)

Explicit tool/URL selections are fail-closed. If that browser session is not open, the call fails instead of falling back to another Viewer. Fallback applies only when no session was selected explicitly. Responses are accepted only from the WebSocket that owns the pending request.

HTTP Push API

For non-MCP integrations (e.g., FastAPI backends), the runtime exposes an HTTP endpoint:

curl -X POST http://localhost:9100/push \
  -H "Content-Type: application/json" \
  -d '{"action": "flyTo", "params": {"longitude": 2.29, "latitude": 48.86, "height": 1000}}'

Common Types

ColorInput

type ColorInput =
  | string                        // CSS color: "#FF0000", "red", "rgba(255,0,0,0.5)"
  | { red: number; green: number; blue: number; alpha?: number }  // RGBA 0–1

MaterialInput

type MaterialInput =
  | ColorInput
  | {
      type: "color" | "image" | "checkerboard" | "stripe" | "grid"
      color?: ColorInput
      image?: string
      evenColor?: ColorInput
      oddColor?: ColorInput
      orientation?: "horizontal" | "vertical"
      cellAlpha?: number
    }

PositionDegrees

type PositionDegrees = {
  longitude: number   // degrees
  latitude: number    // degrees
  height?: number     // meters
}