Routing24 as an MCP server
By Nathan ColeUpdated
Routing24 publishes a Model Context Protocol server at
https://routing24.ai/mcp. An assistant that supports MCP lists the tools
Routing24 offers and calls them. This page covers how a call is routed to
your plan, the 43 tools the server exposes, what the app shows while a
connected assistant works, and what each failure means.
How a call is routed to your plan
A call is routed in three steps. The work happens at the last one:
- The connected assistant sends the call to
https://routing24.ai/mcp. - The server routes it into your signed-in Routing24 browser tab.
- The tab performs the work on the plan it has open, and answers.
Three conditions follow from that routing. Most failures on this page come from one of them:
- You are signed in to Routing24 in a browser.
- A
routing24.com/apptab is open. Any page of the app qualifies. - You approved the connection once from that browser. See Connect Claude and ChatGPT.
One browser at a time serves the account. When you approve the connection in a second browser, the first one stops answering.
The assistant in the app does the same work through the same tools. The two differ in what surrounds them:
| The assistant in the app | A connected assistant |
|---|---|
| Opens in the app, no setup | Connect once with a URL and an approval |
| Can access the plan, not your files or other systems | Accesses your files, mail, and other tools too |
| Imports a file you attach, saves a converter, reviews an address repair | Uses the 43 tools only |
| Spends the account's AI budget | Spends its own provider budget |
| Runs while the pane is open | Needs any app tab open, on any page |
What Routing24 exposes
Every tool is prefixed routing24_. The vocabulary a connected assistant
reads is the vocabulary the app uses: time windows, capacities, shifts,
priorities, tags, breaks, transfers, sequences, reloads, and costs.
A tool marked read below only reads. It cannot change the plan, and the server declares it as such, which is what a client groups its permissions by. Everything unmarked writes.
Plans and the account
| Tool | What it does |
|---|---|
Get auth userreadrouting24_get_auth_user | The signed-in account a saved plan will belong to |
List plansreadrouting24_list_plans | The saved plans: id, name, timestamps, entity counts, and which one is loaded |
Load planrouting24_load_plan | Load a saved plan by id, saving the replaced plan's unsaved changes first |
New planrouting24_new_plan | Start a fresh empty plan, replacing the loaded one after saving its unsaved changes |
Saverouting24_save | Persist the plan and return its link |
Plan URLreadrouting24_plan_url | The current plan's link |
Reading the routing plan
| Tool | What it does |
|---|---|
Statusreadrouting24_status | Progress plus the routing plan overview: rollups, cost, and per-route stats |
Routereadrouting24_route | One route's ordered stops by its on-screen route number: ETAs, loads, waits, and problems |
Unassignedreadrouting24_unassigned | Which orders are unassigned and why: ids, diagnostics, and insertion quotes |
Plan data
| Tool | What it does |
|---|---|
List stopsreadrouting24_list_stops | Read the plan's orders, paged and filterable |
List vehiclesreadrouting24_list_vehicles | Read the plan's vehicle types |
List depotsreadrouting24_list_depots | Read the plan's depots |
Geocode addressesreadrouting24_geocode_addresses | Check up to 10 addresses against the geocoder: whether each one resolves and the address it matched, creating nothing |
Upsert stopsrouting24_upsert_stops | Create or update orders by id; a row with only an id and an address is how an address list enters the plan |
Upsert vehiclesrouting24_upsert_vehicles | Create or update vehicle types by id |
Upsert depotsrouting24_upsert_depots | Create or update depots by id |
Delete stopsrouting24_delete_stops | Delete orders by id |
Delete vehiclesrouting24_delete_vehicles | Delete vehicle types by id |
Delete depotsrouting24_delete_depots | Delete depots: the vehicles referencing them are deleted with them |
Route editing
| Tool | What it does |
|---|---|
Move stopsrouting24_edit_move_stops | Move stops to another route or another position, anchored or at the cheapest position |
Unassign stopsrouting24_edit_unassign_stops | Take stops off their routes |
Set route vehiclerouting24_edit_set_route_vehicle | Give a route a different vehicle |
Create routerouting24_edit_create_route | Add an empty route for a vehicle |
Remove routesrouting24_edit_remove_routes | Delete routes: stops still on them are unassigned in the same edit |
Split routerouting24_edit_split_route | Split a route in two after a stop |
Merge routesrouting24_edit_merge_routes | Move other routes' stops onto one route |
Mark user assignedrouting24_edit_mark_user_assigned | Mark stops as placed manually, with a report of what that breaks |
Clear user assignedrouting24_edit_clear_user_assigned | Drop that mark and its report |
Undorouting24_undo | Step back through the shared edit history |
Redorouting24_redo | Step forward again |
Optimization
| Tool | What it does |
|---|---|
Reoptimize planrouting24_reoptimize_plan | Optimize the loaded plan in place |
Reoptimize routerouting24_reoptimize_route | Re-sequence one route, synchronously |
Cancelrouting24_cancel | Abort a long optimization, keeping the best routing plan so far |
Data and scripting
| Tool | What it does |
|---|---|
SQL queryreadrouting24_sql_query | Read the plan with SQL over eight live tables, orders to routing plan stops |
SQL updaterouting24_sql_update | Bulk field updates with SQL, validated and applied atomically |
Run scriptrouting24_run_script | Sandboxed JavaScript transforms and analysis over a draft of the plan |
The app and the output
| Tool | What it does |
|---|---|
Renderreadrouting24_render | Navigate to the optimization page so the routes draw |
Open pagereadrouting24_open_page | Open one of the app's pages |
Show on mapreadrouting24_show_on_map | Fly the map to an order or depot |
Export Excelreadrouting24_export_excel | Download the plan as an Excel workbook |
Map imagereadrouting24_map_image | Snapshot the plan as a Retina map image, pins and route lines |
Session logreadrouting24_session_log | Read an assistant session's action log, for handovers and audits |
Tabs and sessions
| Tool | What it does |
|---|---|
List loaded plansreadrouting24_list_loaded_plans | The open tabs, the plan open in each, and the assistant session editing it |
Coordinates instead of an address
An order or a depot needs a location. You normally give it an address, and Routing24 geocodes that address when it saves the row.
When you already know the exact point, put coordinates on the row instead,
with a lat and a lng in decimal degrees. Routing24 places the row at that
point and never calls the geocoder. Add an address as well to keep your own
text on the row. Without one the row reads 25.19882, 55.27939.
An address written as two decimal numbers does the same thing. Send
25.19882, 55.27939 as the address and the row lands on that point.
Both forms work on routing24_upsert_stops and routing24_upsert_depots, and
both work a whole batch at a time. A list of points you already hold goes in
as one call, with nothing left for the geocoder to get wrong.
Coordinates only go in. No tool gives them back.
Which plan a call targets
A browser can have several plans open, one per tab. Two inputs decide which plan a call targets.
plan_id identifies the plan the call must operate on. That plan has to be
open in a tab already. When no tab has it open, the call fails and names
the plans that are open.
session_id identifies a connected assistant's own editing session.
Routing24 mints one on the assistant's first change to a plan and returns
it in the result. An assistant that pins that id on every later call keeps
its own plan, even when you switch to a different tab. Read-only calls
never mint a session.
routing24_list_loaded_plans reports the open tabs, the plan each one has
open, whether the tab is empty, focused, or visible, and the assistant
session editing it. Two assistants working on two plans use it to keep
their calls on their own plans.
With neither input, the call operates on the caller's own session plan. With no session, it operates on the plan in the focused tab, then in a visible tab, then in the tab seen most recently. The focused tab changes whenever you click another one.
What you see while a connected assistant works
- The header badge. On plan-scoped pages, a green badge reads the
client name and how long ago it called, for example
Claude (now)orChatGPT (3 min ago). Its tooltip shows the last tool by its wire name: "Last action by Claude: routing24_reoptimize_plan. Click for the session log." The badge disappears five minutes after the last call. Press it to open the assistant pane on the log. - The session log. The assistant pane lists each session under a
heading reading
Session a1b2c3d4 (Claude), then one row per call with the time, the action in plain words, and whether it failed. Lifecycle rows read "started this session", "took over this session", and "resumed in another tab". - The disconnect bar. Below the message box, a bar reads "Claude is connected to your account" with a Disconnect button. See Connect Claude and ChatGPT.
- The lock. An edit puts the app behind a full-screen overlay titled Agent controlled, reading "An AI agent is editing this plan. The screen is locked while it works; every change lands in the shared undo history.", with a counter of the changes applied so far. Press Take control to take the app back at any moment.
- The pane. While a connected assistant is working, the message box is replaced by "Claude is working on this plan" and a Take control button.
A connected assistant's deletes and bulk field changes apply without a review. The review dialogs belong to the assistant in the app.
Shared editing
The connected assistant's edits and your own edits share one undo history. Continue manually exactly where the assistant stopped. See Query, edit, and export a plan with AI.
When the plan changed since the connected assistant last read it, Routing24 rejects that assistant's next edit. Nothing is written. The rejection includes the plan's current revision and the last editor. The assistant re-reads the plan, and the same call succeeds on the retry. The app shows nothing while this happens.
What the errors mean
A connected assistant reports these in its own transcript.
| What the assistant reports | What happened |
|---|---|
| No Routing24 browser tab is connected | No signed-in browser is attached. Open the app and sign in |
| No Routing24 app tab is open | The browser is attached, but no app tab is open. Open routing24.com/app |
| The tab closed while running a tool | The tab closed mid-call. The change may or may not have applied |
| The tab did not answer within 60s | A tool exceeded the 60-second limit. A running optimization continues in the tab |
| Another tab took over while this call was running | A second browser attached and superseded the first |
| Plan state drifted | The plan changed since the assistant last read it. It re-reads and retries |
A long optimization always exceeds the 60-second limit. The optimization
keeps running in the tab. The assistant polls routing24_status for the
result instead of repeating the call.
Limits
- Eight calls in flight at once per session.
- 120 requests a minute per account.
- 60 seconds per call.
- A map image of around 600 KB.
- A visible tab for a map image. A hidden window stops painting, so the capture times out.
- One browser attached per account. A connected assistant works through that browser and nowhere else: Routing24 runs nothing on its own behalf while every tab is closed.
Where the work runs
The optimization runs in your browser tab. Geocoding and distance matrices run on Routing24 servers under your own session. The MCP endpoint is the only Routing24 server a connected assistant accesses, with a token minted when you approve the connection. Privacy and data handling states what each of those calls sends and who receives the data a connected assistant reads.
What it costs
Connecting an assistant is available on every tier. A connected assistant spends its own provider budget rather than the account's AI budget. An optimization it starts spends the same allowance as the Optimize button. See Describe constraints in plain language and Plans and billing.
The Optimization API is a separate Pro product for system-to-system integration, set up with the team. See Integrations.
Next step
The write tools set the same fields you set manually. Add vehicles and depots opens the reference for what those fields mean.
FAQ
What do I need for a connected assistant to work?
A connected assistant needs three things: you are signed in to Routing24 in a browser, a routing24.com/app tab is open on any page of the app, and you approved the connection once from that browser. One browser at a time serves the account; approving the connection in a second browser stops the first one from answering.
Where does a connected assistant's work actually run?
The call is routed into your signed-in browser tab, and the tab performs the work on the plan it has open. The optimization runs in the browser. Geocoding and distance matrices run on Routing24 servers under your own session. The MCP endpoint is the only Routing24 server a connected assistant accesses.
How is a connected assistant different from the assistant in the app?
Both do the same work through the same tools. The assistant in the app opens with no setup, can access the plan but not your files or other systems, and spends the account's AI budget. A connected assistant connects once with a URL and an approval, accesses your files and other tools too, and spends its own provider budget.
Can I stop a connected assistant while it is editing?
Yes. An edit puts the app behind a full-screen overlay titled Agent controlled, with a counter of the changes applied so far. Press Take control to take the app back at any moment. Every change lands in the shared undo history, so you can continue manually exactly where the assistant stopped.
Why does a long optimization time out for a connected assistant?
Every call has a 60 second limit, and a long optimization always exceeds it. The optimization keeps running in the tab; only the call ends. The assistant polls the status tool for the result instead of repeating the call and reads the routing plan when the run finishes.