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 45 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 45 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 |
|---|---|
routing24_get_auth_userread | The signed-in account a saved plan will belong to |
routing24_list_plansread | The saved plans: id, name, timestamps, entity counts, and which one is loaded |
routing24_load_plan | Load a saved plan by id, saving the replaced plan's unsaved changes first |
routing24_new_plan | Start a fresh empty plan, replacing the loaded one after saving its unsaved changes |
routing24_save | Persist the plan and return its link |
routing24_plan_urlread | The current plan's link |
Reading the routing plan
| Tool | What it does |
|---|---|
routing24_statusread | Progress plus the routing plan overview: rollups, cost, and per-route stats |
routing24_routeread | One route's ordered stops by its on-screen route number: ETAs, loads, waits, and problems |
routing24_unassignedread | Which orders are unassigned and why: ids, diagnostics, and insertion quotes |
Plan data
| Tool | What it does |
|---|---|
routing24_list_stopsread | Read the plan's orders, paged and filterable |
routing24_list_vehiclesread | Read the plan's vehicle types |
routing24_list_depotsread | Read the plan's depots |
routing24_list_addressesread | Read the address book, with usage counts |
routing24_upsert_stops | Create or update orders by id |
routing24_upsert_vehicles | Create or update vehicle types by id |
routing24_upsert_depots | Create or update depots by id |
routing24_upsert_addresses | Create or update address-book rows |
routing24_delete_stops | Delete orders by id |
routing24_delete_vehicles | Delete vehicle types by id |
routing24_delete_depots | Delete depots: the vehicles referencing them are deleted with them |
routing24_delete_addresses | Delete addresses: the orders and depots at them are deleted with them |
Route editing
| Tool | What it does |
|---|---|
routing24_edit_move_stops | Move stops to another route or another position, anchored or at the cheapest position |
routing24_edit_unassign_stops | Take stops off their routes |
routing24_edit_set_route_vehicle | Give a route a different vehicle |
routing24_edit_create_route | Add an empty route for a vehicle |
routing24_edit_remove_routes | Delete routes: stops still on them are unassigned in the same edit |
routing24_edit_split_route | Split a route in two after a stop |
routing24_edit_merge_routes | Move other routes' stops onto one route |
routing24_edit_mark_user_assigned | Mark stops as placed by hand, with a report of what that breaks |
routing24_edit_clear_user_assigned | Drop that mark and its report |
routing24_undo | Step back through the shared edit history |
routing24_redo | Step forward again |
Optimization
| Tool | What it does |
|---|---|
routing24_reoptimize_plan | Optimize the loaded plan in place |
routing24_reoptimize_route | Re-sequence one route, synchronously |
routing24_cancel | Abort a long optimization, keeping the best routing plan so far |
Data and scripting
| Tool | What it does |
|---|---|
routing24_sql_queryread | Read the plan with SQL over eight live tables, orders to routing plan stops |
routing24_sql_update | Bulk field updates with SQL, validated and applied atomically |
routing24_run_script | Sandboxed JavaScript transforms and analysis over a draft of the plan |
The app and the output
| Tool | What it does |
|---|---|
routing24_renderread | Navigate to the optimization page so the routes draw |
routing24_open_pageread | Open one of the app's pages |
routing24_show_on_mapread | Fly the map to an order, depot, or address |
routing24_export_excelread | Download the plan as an Excel workbook |
routing24_map_imageread | Snapshot the plan as a Retina map image, pins and route lines |
routing24_session_logread | Read an assistant session's action log, for handovers and audits |
Tabs and sessions
| Tool | What it does |
|---|---|
routing24_list_loaded_plansread | 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 by hand 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, billing, and free limits.
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 by hand. 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 by hand 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.