MCP tools
Nostalgija exposes a Model Context Protocol server at /_mcp, protected by the same
OAuth 2.1 layer as the REST API. AI agents (Claude, Gemini, Cursor) connect, authorize with the
video:read / video:create scopes, and call the tools below.
The list is generated automatically from the tool definitions in the codebase, so it always matches what the server actually offers.
check_video_status
Check whether a video render has finished. Returns its status (pending, rendering, complete, failed). Rendering takes a few minutes - do NOT poll in a tight loop; wait the interval the response suggests (about 30s) before calling again. When complete, the response includes a ready-to-open download link.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
video_id |
int |
yes | - | The id returned by create_route_video / create_earth_zoom_video. |
create_earth_zoom_video
FINAL step of the earth-zoom flow - actually starts the render and spends one credit. Call this ONLY after plan_earth_zoom_video has been used to walk the user through the Q&A (projection, end zoom, duration, map style, motion blur, resolution), OR when the user explicitly says "use defaults / just render it / skip the questions". For any open-ended "zoom from space" request, call plan_earth_zoom_video FIRST. Renders asynchronously; returns a video_id to poll with check_video_status.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
location |
string |
yes | - | Where to zoom to: a place name/address ("Times Square, New York") or "lat,lng". |
projection |
string |
no | flat |
"globe" (spins in from a 3D globe) or "flat" (flat map). Default flat. |
start_zoom |
float |
no | 0 |
Starting zoom, 0.5-10. Lower = further out in space. Default 0.8 for globe, 2 for flat. |
end_zoom |
float |
no | 16 |
Final zoom, 5-22. Higher = closer to the ground. Default 16. |
duration |
float |
no | 6 |
Length of the zoom in seconds, 1-60. Default 6. |
map_style |
string |
no | osm |
osm, cartodb_dark, cartodb_light, esri_satellite, stamen_watercolor, opentopomap. Default osm (use esri_satellite for a realistic Earth look). |
blur_effect |
bool |
no | false |
Add motion blur during the zoom. Default false. |
resolution |
string |
no | 1920x1080 |
1920x1080 (landscape), 1080x1920 (portrait/reels), 1080x1080 (square). Default 1920x1080. |
create_route_video
FINAL step of the route-animation flow - actually starts the render and spends one credit. Call this ONLY after plan_route_video has been used to walk the user through the Q&A (vehicle, camera, speed, map style, weather, trail, resolution), OR when the user explicitly says "use defaults / just render it / skip the questions". For any open-ended "make a video from A to B" request, call plan_route_video FIRST, not this tool. Renders asynchronously; returns a video_id to poll with check_video_status.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
origin |
string |
no | "" |
Start of the route: a place name or address ("Zagreb", "Eiffel Tower, Paris") or "lat,lng". Leave empty when google_maps_url is given. |
destination |
string |
no | "" |
End of the route: place name/address or "lat,lng". Leave empty when google_maps_url is given. |
google_maps_url |
string |
no | "" |
A Google Maps directions URL the user pasted (https://www.google.com/maps/dir/... or a maps.app.goo.gl short link). When given, the exact route polyline is imported from it and origin/destination/stops are ignored - use this whenever the user supplies a Maps link instead of place names. |
stops |
array |
no | [] |
Optional intermediate stops in order, each a place name/address or "lat,lng". Ignored when google_maps_url is given. |
vehicle_icon |
string |
no | car |
Icon that travels the route. One of: car, motorcycle, bicycle, truck, bus, airplane, train, boat, walking, camper. Default car. An airplane flies the great-circle path between the waypoints instead of following roads (unless the route comes from a google_maps_url, which is used verbatim). |
camera_follow |
bool |
no | true |
true = camera tracks the vehicle (cinematic close-up); false = static view of the whole route. Default true. |
speed |
int |
no | 60 |
Animation speed 1-500. Guidance: ~30 very leisurely, ~60 gentle, ~120 brisk, ~300 fast. Higher = shorter video. Default 60. |
map_style |
string |
no | osm |
osm, cartodb_dark, cartodb_light, esri_satellite, stamen_watercolor, opentopomap. Default osm. |
trail_effect |
string |
no | solid |
solid, exhaust, dotted_chalk, footprint. Default solid. |
weather_effect |
string |
no | none |
none, rain, snow, sun. Default none. |
vehicle_color |
string |
no | #e63946 |
Hex colour for the icon, e.g. "#e63946". Optional. |
trail_color |
string |
no | #e63946 |
Hex colour for the trail. Optional. |
resolution |
string |
no | 1920x1080 |
1920x1080 (landscape), 1080x1920 (portrait/reels), 1080x1080 (square). Default 1920x1080. |
list_my_videos
List the most recent videos on the authenticated Nostalgija account, with their status.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit |
int |
no | 5 |
How many recent videos to return (1-20). Default 5. |
nostalgija_ping
Health check. Returns "pong" plus the echoed message, to confirm the Nostalgija MCP server is reachable.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
message |
string |
no | hello |
plan_earth_zoom_video
START HERE for any "zoom from space / Google Earth style intro / fly down to a place" request. Returns a step-by-step Q&A script the agent MUST walk the user through (projection, end zoom, duration, map style, motion blur, resolution) before calling create_earth_zoom_video. Does NOT render anything and does NOT cost credits.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
location |
string |
no | "" |
Where to zoom to: a place name/address ("Times Square, New York") or "lat,lng". |
plan_route_video
START HERE for any "animate / visualise / make a video of a route, trip, journey, drive, ride, commute" request between two or more places. Returns a step-by-step Q&A script the agent MUST walk the user through (vehicle, camera, speed, map style, weather, trail, resolution) before calling create_route_video. Does NOT render anything and does NOT cost credits.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
origin |
string |
no | "" |
Start of the route: a place name or address ("Zagreb", "Eiffel Tower, Paris") or "lat,lng". Leave empty when google_maps_url is given. |
destination |
string |
no | "" |
End of the route: place name/address or "lat,lng". Leave empty when google_maps_url is given. |
stops |
array |
no | [] |
Optional intermediate stops in order. Ignored when google_maps_url is given. |
google_maps_url |
string |
no | "" |
Optional Google Maps directions URL the user pasted. When given, origin/destination/stops are ignored. |