FAQ

Connection Issues

WebSocket connection failed

Symptom: The browser console shows WebSocket connection to 'ws://localhost:9100' failed.

Solutions:

1. Make sure cesium-mcp-runtime is running: npx -y cesium-mcp-runtime
2. Check the port — if port 9100 is in use, set a custom port:

   CESIUM_WS_PORT=9200 npx -y cesium-mcp-runtime

   The runtime will automatically listen on the new port.
3. If using HTTPS, the browser blocks mixed content (wss:// is required). Use a reverse proxy or tunnel (e.g. ngrok).

Bridge connects but tools don't work

Symptom: The runtime log shows browser connected, but AI tool calls return errors.

Solutions:

1. Ensure the CesiumJS Viewer is fully initialized before creating the bridge
2. Check the browser console for JavaScript errors
3. Verify the sessionId matches between bridge and runtime (default: 'default')

Tool Issues

"No browser connected" error

The runtime can't find a connected browser session.

1. Open the built-in Viewer at http://localhost:9100/?session=default, or open your custom CesiumJS page
2. For a custom page, check that its Runtime WebSocket connection is initialized
3. If using multiple tabs, set unique sessionId for each

Only some tools are available

By default, only core toolsets are enabled. To enable all 62 command tools:

CESIUM_TOOLSETS=all npx -y cesium-mcp-runtime

Or use dynamic discovery — ask your AI agent: "List available toolsets", then "Enable the animation toolset".

flyTo doesn't animate

If flyTo jumps instead of animating, check:

1. The duration parameter (default: 2 seconds)
2. CesiumJS scene mode — 2D mode doesn't support smooth fly-to
3. Some AI clients have short timeouts — increase the MCP timeout if needed

Configuration

How to use a Cesium Ion access token?

Set your token in the CesiumJS app before creating the Viewer:

Cesium.Ion.defaultAccessToken = 'YOUR_TOKEN_HERE'

The bridge doesn't handle tokens — they are managed by your CesiumJS application.

How to change the WebSocket port?

Set the CESIUM_WS_PORT environment variable:

CESIUM_WS_PORT=9200 npx -y cesium-mcp-runtime

Can I use remote/cloud mode?

Yes. The runtime supports Streamable HTTP mode for remote access:

npx -y cesium-mcp-runtime --transport http --port 3000

Or use the hosted endpoint at https://mcp.gpb.cc.

Compatibility

Which CesiumJS versions are supported?

cesium-mcp v1.145.x is built and tested against CesiumJS ~1.145.0. The Bridge peer dependency is the authoritative compatibility range. New official CesiumJS releases are reviewed before that range and affected tool contracts are updated.

Which AI clients work?

Any MCP-compatible client works:

• Claude Desktop — full support
• VS Code GitHub Copilot — full support
• Cursor — full support
• Windsurf — full support
• Custom clients — any implementation following the MCP specification

Does it work with TypeScript?

Yes. All packages ship with TypeScript declarations. The bridge exports all type definitions:

import type { BridgeCommand, EntityOptions, LayerInfo } from 'cesium-mcp-bridge'