# Connect an AI agent to SpatialBay and GeoMotion This page is written for AI agents (Claude Code, Claude, ChatGPT, Cursor, Codex) and for the people using them. If someone gave you this link, follow the steps for the app you are running in. When you are done, check the connection and tell the person what you can do for them. SpatialBay makes maps from real geographic data (https://spatialbay.app). GeoMotion turns places, routes and maps into short cinematic map videos (https://geomotion.spatialbay.app). Both are reached through one MCP server: https://api.spatialbay.app/mcp The person signs in to SpatialBay in their browser and approves the connection once, by clicking Allow on a link you give them. No password is pasted into the chat. Heavy work (fetching data, compiling animations, rendering video) runs on SpatialBay's servers and render machine, not on the person's computer. Finished videos come back as an MP4 link. ## 1. Is it already connected? If you already have tools from a server called `spatialbay` (for example `connection_status`, `create_motion`, `list_maps`), call `connection_status` and skip to step 3. ## 2. Connect ### Claude Code, Codex, Cursor and other agents that run commands (Windows, macOS, Linux) Use pairing. It needs only `curl` (Git Bash, PowerShell's `curl.exe`, macOS and Linux all have it) and one click from the person. Do every step yourself; the person only opens a link and clicks Allow. 1. Start a pairing (put your own name in `app`): ```bash curl -s -X POST "https://api.spatialbay.app/oauth/pair?app=Claude%20Code" ``` The answer has `code` (like `K7QM-4XTD`), `open` (a link), `device_code` and `poll` (the exact command for step 3). 2. Give the person the `say` line from the answer: the link and the code. Open the link for them too if you can (Windows: `cmd.exe /c start "" ""`, macOS: `open ""`, Linux: `xdg-open ""`). On that page they sign in, or make a free account and come straight back, check the code matches and click **Allow**. 3. Run the `poll` command every 3 seconds (up to 15 minutes) until `status` is `approved`. While it says `pending`, wait. The approved answer has `access_token` and `claude_code`, the ready command for step 4. The token is handed out once. 4. Add the server with it (remove an older `spatialbay` entry first, it does no harm if there is none): ```bash claude mcp remove spatialbay -s user claude mcp add --transport http --scope user spatialbay https://api.spatialbay.app/mcp --header "Authorization: Bearer " ``` Codex: `[mcp_servers.spatialbay]` with `url` and `http_headers = { Authorization = "Bearer " }` in `~/.codex/config.toml`. Cursor: `~/.cursor/mcp.json` with the same URL and header. 5. Claude Code loads new servers when a session starts: ask the person to type `/mcp` and reconnect `spatialbay`, or start a new session. Then call `connection_status` (step 3 below). Never repeat the token in the chat. Claude Code can also sign in by itself: `claude mcp add --transport http --scope user spatialbay https://api.spatialbay.app/mcp`, then `/mcp` → `spatialbay` → **Authenticate**. If that shows "SDK auth failed" (seen on Windows), use pairing above instead. Never ask the person for their SpatialBay password. ### Claude (claude.ai and Claude Desktop) The person adds it themselves: **Settings → Connectors → Add custom connector**. Name `SpatialBay`, URL `https://api.spatialbay.app/mcp`, then **Connect** and **Allow** in SpatialBay. Turn the connector on in a chat from the tools menu. ### ChatGPT **Settings → Apps & Connectors → Advanced → Developer mode** on, then **Create**: name `SpatialBay`, URL `https://api.spatialbay.app/mcp`, authentication **OAuth**. Approve in SpatialBay. ### Cursor, VS Code, Codex and other apps Add an HTTP MCP server named `spatialbay` with the URL `https://api.spatialbay.app/mcp`. Apps that support OAuth open the browser to approve. Others need a token from https://spatialbay.app/#/connect sent as `Authorization: Bearer `. Only GeoMotion's tools: `https://api.spatialbay.app/mcp/geomotion`. Only SpatialBay's map tools: `https://api.spatialbay.app/mcp/spatialbay`. ## 3. Check the connection and tell the person Call `connection_status`. It returns: - `person` and `workspace`: who you act as. - `via`: `oauth` (an app they approved), `token`, or `session`. `connection` gives its name and when it was last used. - `geomotion`: either `paid` (no video limit) or `freeVideos` (`left` of `of`, each up to `maxSeconds`). - `summary`: one line you can repeat to them. Tell them in one line, for example: "Connected to SpatialBay as Amina (amina@example.com). You have 2 free videos of up to 15 s." SpatialBay's administrators are told when someone connects an AI, and see each connection's name and when it was last used. ## 4. Make a map video 1. `find_place` for each place you need. 2. `create_motion` with a program: the look, real sources by name (a route by its stops, a country, a river, a border, a SpatialBay layer), a camera that starts wide and pushes in, the route drawing on, markers, short labels. Read `get_guide('overview')` and `motion_reference` first if you have not. 3. `preview_motion` and look at the frames. Fix what is wrong with `update_motion` or `review_motion` (apply: true). 4. `render_motion`, then poll `get_motion_render` every 15 to 30 seconds. A short video takes a few minutes. 5. When it is done, give the person the `videoUrl`. If you can run commands, save it for them: ```bash curl -L -o my-map-video.mp4 "" ``` Lines and shapes always come from real data. Never write coordinates by hand as geometry. ### Free videos People without a GeoMotion plan get **2 free videos**, each up to **15 seconds**, rendered quickly at 720p. Longer programs are shortened to 15 s when they are made. Previews are limited to 20 a day while free videos are left. After that, `render_motion` answers "free_videos_used" with a link to the plans (https://spatialbay.app/#/pricing). Preview before you render so the free videos are not spent on a wrong cut. ## 5. Maps and data With a SpatialBay plan the same connection builds maps: `create_map`, `get_geodata` (real open data by name, kept in the Data Hub), `add_layers_to_map`, `style_layer`, `set_legend`, `set_title_card`, and `motion_from_map` to animate a map as it is styled. `list_maps`, `get_map`, `list_layers` and `get_layer_features` read what the person already has. Every change shows in the SpatialBay app at https://spatialbay.app/#/maps. ## 6. When something fails - `401 unauthorized`: not connected, or the connection was removed or expired (after 90 days). Pair again (step 2), or reconnect the connector. - "SDK auth failed" in Claude Code's `/mcp`: its own sign-in did not work on this machine. Use pairing (step 2). - `402`: the action needs a plan or credits, or the free videos are used up. Tell the person and give them https://spatialbay.app/#/pricing. - `403 insufficient_scope`: the token is for the other product. Use the matching URL above or make an "all tools" token. People can see and remove their connections at https://spatialbay.app/#/connect.