Docs

Roadbook MCP API

See what is included in Premium

New to this? Use Roadbook in Claude or ChatGPT.

Roadbook exposes a Model Context Protocol(MCP) server so an AI agent can plan and manage trips on a user's behalf. The endpoint speaks JSON-RPC 2.0 over a single route.

Connect Roadbook to Claude

  1. In Claude, add a custom connector with the URLhttps://roadbook.us/mcp.
  2. Select Connect. Roadbook opens and asks you to sign in with your email or your Bluesky account.
  3. Review the consent screen and select Allow access.
  4. Ask Claude about your trips. Tool calls need an active premium subscription.

Example prompts:

  • "List my Roadbook trips and show the stops on my next one."
  • "Add Arches National Park as a stop on my Utah trip."
  • "Here is my hotel confirmation email. Add the booking to the right stop on my trip."
  • "Add a logbook entry for yesterday's drive from my notes."

Endpoint

POST /mcp accepts a JSON-RPC 2.0 request (or a batch array of up to 50) and dispatches on the methodfield - initialize,tools/list, andtools/call are the ones an MCP client needs. The machine-readable request/response envelope is published as OpenAPI at/openapi.json. Every tool and its input fields are listed under Tools.

Authentication

Every request needs a bearer token in the Authorization header. Two ways to get one:

  • OAuth 2.0 - discover the authorization server at/.well-known/oauth-authorization-server(RFC 8414) and the protected-resource metadata at/.well-known/oauth-protected-resource(RFC 9728). Dynamic client registration, PKCE (S256), and theauthorization_code andrefresh_token grants are supported.
  • Personal token - a signed-in user can mint a long-lived token from their account settings for scripting or local MCP clients that don't support OAuth.

Access

Connecting and listing tools is free. Every tool call needs an active premium subscription. Any authenticated, non-banned Roadbook account can run initialize and tools/list. The premium check runs at tools/call time, not at connection time.

Troubleshooting

  • "This tool needs a Roadbook Premium account." Your account is on the free plan. Upgrade at /billing, then retry.
  • Claude asks you to connect again. Your access was revoked. Generating or regenerating a personal token in Basecamp settingsrevokes every connected assistant. Reconnect from Claude.
  • "This account is suspended." Contact us throughsupport.
  • Too many requests. Wait, then retry.
  • Disconnect. Remove the connector in Claude. To revoke access for every assistant at once, regenerate your personal token in Basecamp settings.

Tools

30 tools, generated from the server's own tools/list response, so every field below is one a client sees. Each badge says what a tool does to your data, not which plan can call it. The badge comes from the tool's MCP annotations: Read-only never changes data, Writes adds or edits, and Destructive can remove data.

list_tripsRead-only

List trips

List the trips you own, most recently updated first. Returns trips: [{id, name, slug, visibility, startDate, updatedAt}] (startDate can be null) and nextCursor, null on the last page. Up to 50 trips per page by default.

FieldTypeRequiredNotes
limitintegerOptionalTrips per page, 1 to 100 (default 50)
cursorstringOptionalnextCursor of the previous page. Omit for the first page.

read_tripRead-only

Read trip

Read one of your trips. Returns trip {id, name, slug, visibility, startDate, endDate, journal {hasBody, published}}; stops in order, each with id, role, nights, placeId, name, city, state, the public place lat/lon (not a private stop coordinate), its lodging records and your own chargingReport; drives, the recorded drives with labels, times, distance, duration and energy but no route or exact points (up to 200); lodgingBookingIssues, each night left unbooked (kind "gap") or booked twice (kind "overlap") between consecutive overnight stops, from booked check-in and check-out dates only; vehicle {make, model, trim, rangeKm, rangeKind} or null; and legs, one per pair of consecutive stops, with legKm (a straight-line estimate, not a route; null without place coordinates) and grade (the stored charger-availability letter, or "not graded"; stored grades expire after 24 hours).

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips

create_tripWrites

Create trip

Create a new private trip you own, with no stops. Returns {id, name, slug}. name is required; startDate and endDate (YYYY-MM-DD) are optional, and a malformed date is rejected. Fails when your garage has no vehicle. Each call creates another trip.

FieldTypeRequiredNotes
namestringRequiredTrip name; must not be blank
startDatestringOptionalFirst day of the trip as YYYY-MM-DD, e.g. 2026-07-14. Omit for an undated trip.
endDatestringOptionalLast day of the trip as YYYY-MM-DD, e.g. 2026-07-21. Omit for an undated trip.

search_placesRead-only

Search places

Search real places by name. Returns candidates: [{placeId, name, context, lat, lon, type, url, distanceKm?}]. A place Roadbook stores has its placeId and its public page url (null without a page); a geocoder match not stored yet has placeId and url null. With lat/lng, candidates within radiusKm (default 50) are ranked by distanceKm. type narrows to "settlement", "poi" or an exact type. Without sign-in: stored places only, up to 10, and a query of at least 2 characters.

FieldTypeRequiredNotes
querystringRequiredPlace name or query, e.g. "Moab, UT" or "Zion campground"
latnumberOptionalLatitude to rank places near (give with lng)
lngnumberOptionalLongitude to rank places near (give with lat)
radiusKmnumberOptionalWith lat/lng: keep only candidates within this many km (default 50)
typestringOptionalKeep only this kind: "settlement" (city, town, village), "poi" (anything else), or an exact candidate type such as "campground", "national-park", "hotel"

read_placeRead-only

Read place facts

Read the stored facts for one place by placeId or slug: name, location, categories, a summary and quick facts when a listed source backs them, verified claims (charging, camping, seasonal, events, activities) and the list of sources. Every claim has a sourceUrl and checkedAt, the time it was stored; the quoted passage is not returned. Empty arrays mean no claims are stored. Stored data only: no live availability, no charging reports, no nearby-charger lookup.

FieldTypeRequiredNotes
placeProofobjectOptional
placeIdstringOptionalInternal Place id; include the same candidate placeProof or saved membership. Give this or slug.
slugstringOptionalPublic place slug, the last part of a roadbook.us/explore/places/<slug> URL. Give this or placeId.

fetchRead-only

Fetch place page

Read one place by an id from search. Returns {id, title, text, url, metadata}: text is the JSON of the place facts, the same object read_place returns, with a sourceUrl and checkedAt on every claim; url is the public Roadbook page, left out when the place has none.

FieldTypeRequiredNotes
placeProofobjectOptional
idstringRequiredPublic place URL from search; an internal id needs its candidate placeProof or saved membership

submit_placeWrites

Submit a place

Queue a place that is missing from search for a human moderator. Creates no live place: returns {submitted: true, submissionId, status: "pending"}. When the place already exists or the same submission is pending, nothing is queued and the match comes back with submitted: false. Fails while you have 10 submissions awaiting moderation.

FieldTypeRequiredNotes
namestringRequiredPlace name, max 200 characters
type"campground" | "hotel" | "motel" | "inn" | "rental" | "dispersed" | "park" | "trailhead" | "viewpoint" | "charger" | "restaurant" | "other"RequiredType of place: campground, hotel, motel, inn, rental, dispersed, park, trailhead, viewpoint, charger, restaurant, other
citystringRequiredCity, max 120 characters
statestringRequiredState or region, max 120 characters
addressstringOptionalStreet address for the moderator, max 300 characters. Not published as a precise coordinate.
notesstringOptionalNotes for the moderator, max 2000 characters

create_stopWrites

Create stop

Add a stop to one of your trips by place query, by candidateRef, or by exact lat/lng. A coordinate resolves to the city or neighborhood around it: the trip shows that place and the exact point stays on the private stop. An ambiguous query creates nothing and returns candidates, each with a ref, coordinates, type and, when the trip has stops, distanceKm from the last stop; a ref passed as candidateRef adds that exact place. beforeWaypointId inserts the stop before that top-level stop and is not remembered between calls; without it the stop is appended. The lodging fields record one booking in the same call (lodgingName is required once any is set). Returns {created: true, waypointId, placeName, sortOrder}.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
querystringOptionalPlace name or query. Give this, a candidateRef, or lat/lng.
latnumberOptionalExact latitude of the stop (give with lng), resolved to its city or neighborhood
lngnumberOptionalExact longitude of the stop (give with lat)
labelstringOptionalPrivate label for a coordinate stop, e.g. "Home" or "Trailhead parking"
candidateRefstringOptionalThe ref of a candidate from an earlier ambiguous result, to add that exact place
role"departure" | "stop" | "destination"OptionalRole of the stop (default stop)
beforeWaypointIdstringOptionalInsert before this top-level stop. Omit to append at the end.
lodgingNamestring | nullOptionalLodging name, max 200 characters. Required when a stop gets its first lodging record; cannot be cleared.
lodgingType"campground" | "hotel" | "motel" | "inn" | "rental" | "dispersed" | "other" | nullOptionalType of lodging, one of: campground, hotel, motel, inn, rental, dispersed, other. Null clears it.
checkInstring | nullOptionalCheck-in date as YYYY-MM-DD, e.g. 2026-07-14. Null clears it.
checkOutstring | nullOptionalCheck-out date as YYYY-MM-DD, not earlier than checkIn. Null clears it.
costnumber | nullOptionalTotal cost of the stay, 0 or more, in the units of currency. Null clears it.
currencystring | nullOptionalISO 4217 currency code for cost, e.g. USD or EUR. Null clears it.
reservationRefstring | nullOptionalBooking confirmation or reservation reference, max 200 characters. Null clears it.
lodgingNotesstring | nullOptionalNotes about the lodging, max 2000 characters. Null clears it.

update_stopDestructive

Update stop

Change the role, nights, and/or one lodging record of a stop on your trip. lodgingId names the record; it can be left out when the stop has at most one, and a stop with none gets a new record (lodgingName required). Omitted fields stay as they are; null or an empty string clears a lodging field, except lodgingName. Returns {updated: true}.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
waypointIdstringRequiredId of the stop to change
role"departure" | "stop" | "destination"OptionalNew role of the stop. Omit to leave it unchanged.
nightsintegerOptionalNights at this stop, 0 to 365; 0 makes it a day stop
lodgingIdstringOptionalId of the lodging record to change, from read_trip. Needed when the stop has more than one.
lodgingNamestring | nullOptionalLodging name, max 200 characters. Required when a stop gets its first lodging record; cannot be cleared.
lodgingType"campground" | "hotel" | "motel" | "inn" | "rental" | "dispersed" | "other" | nullOptionalType of lodging, one of: campground, hotel, motel, inn, rental, dispersed, other. Null clears it.
checkInstring | nullOptionalCheck-in date as YYYY-MM-DD, e.g. 2026-07-14. Null clears it.
checkOutstring | nullOptionalCheck-out date as YYYY-MM-DD, not earlier than checkIn. Null clears it.
costnumber | nullOptionalTotal cost of the stay, 0 or more, in the units of currency. Null clears it.
currencystring | nullOptionalISO 4217 currency code for cost, e.g. USD or EUR. Null clears it.
reservationRefstring | nullOptionalBooking confirmation or reservation reference, max 200 characters. Null clears it.
lodgingNotesstring | nullOptionalNotes about the lodging, max 2000 characters. Null clears it.

delete_stopDestructive

Delete stop

Delete one top-level stop from your trip, with its sub-stops, and renumber the remaining stops. Cannot be undone. Returns {removed: true}; fails with "Stop not found on this trip" for an unknown id.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
waypointIdstringRequiredId of the top-level stop to delete

reorder_stopsDestructive

Reorder stops

Set the order of the top-level stops on your trip. waypointIds lists every top-level stop id exactly once, in the new order; a partial or foreign list is rejected and nothing changes. Returns {reordered: true}.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
waypointIdsstring[]RequiredEvery top-level stop id of the trip, each exactly once, in the new order

delete_stop_lodgingDestructive

Delete stop lodging

Delete one lodging record from a stop on your trip. The stop keeps its place, position, nights, charging report and logbook entries. lodgingId can be left out when the stop has exactly one record; a stop with several needs it, and a stop with none reports that there was nothing to remove. Cannot be undone. Returns {removed, lodgingId, remaining}.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
waypointIdstringRequiredId of the stop the lodging record is on
lodgingIdstringOptionalId of the lodging record to delete, from read_trip. Can be left out when the stop has exactly one.

suggest_stop_candidatesRead-only

Suggest stop candidates

Read up to 3 real places for one leg or one night of your trip, for the person to choose from. kind "leg" looks along the way from afterWaypointId to the next top-level stop; kind "night" looks near afterWaypointId. Each candidate has placeId, name, city, state, category, detourKm (a straight-line estimate, not a route) and charging: a stored fact with its source, or "no charging data". A leg also returns legKm (straight-line estimate) and rangeKm, the trip vehicle's rated range, or null without a vehicle. Returns no coordinates and changes nothing.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
afterWaypointIdstringRequiredTop-level stop the leg starts at, or the night is near
kind"leg" | "night"Requiredleg = along the way from this stop to the next one; night = near this stop

propose_stopWrites

Propose stop

File one pending stop proposal on your trip, after afterWaypointId, for a placeId from suggest_stop_candidates. The trip does not change: the proposal waits in Roadbook's planner, labeled as proposed by your assistant, until the owner accepts or dismisses it there. No tool accepts or dismisses a proposal. Refused when the place is unknown or not ready, already a stop or already pending on the trip, when afterWaypointId is not a top-level stop, or at 10 pending assistant proposals on the trip. reason is shown to the owner.

FieldTypeRequiredNotes
placeProofobjectOptional
tripIdstringRequiredId of one of your trips
placeIdstringRequiredplaceId of the candidate the person picked, as suggest_stop_candidates returns it
afterWaypointIdstringRequiredTop-level stop the new stop would follow
reasonstringOptionalNote shown to the owner on why this stop, max 500 characters

import_driveDestructive

Import recorded drives

Add 1 to 50 recorded drives (roadbook.drive/1 payloads, as a vehicle connector exports them) to a trip. Without tripId it creates a new private trip; tripId must name one of your private trips. Start and end coordinates resolve to their city or neighborhood. Each drive becomes a departure stop, a destination stop and a drive record (distance, duration, max speed, elevation, energy, route); a drive that starts at the trip's last stop continues from it, which can change that stop's role and nights. A drive already imported (same source.system and source.id) is reported as "exists" and changes nothing. Exact points and the route stay on the private drive record; precision "city" keeps nothing finer than the city. Returns the trip, the stops created, each drive's id and status, and quality notes.

FieldTypeRequiredNotes
tripIdstringOptionalOne of your private trips to add the drives to. Omit to create a new private trip.
tripNamestringOptionalName for a new trip (default: "<start city> to <end city>")
drivesobject[]Required1 to 50 drives, each a roadbook.drive/1 payload exactly as exported
precision"exact" | "city"Optional"exact" (default) keeps the precise start and end points and the route on the private drive record; "city" stores nothing finer than the city

read_logbookRead-only

Read logbook

Read the private logbook of one of your trips. Returns tripId, startDate, coverage and one page of entries, newest first, with nextCursor (null on the last page); startDate and coverage come on the first page only. coverage counts words and characters across all entries: trip totals, per-day averages over the planned span (nights + 1), and overnight stops ranked by words per night, thinnest first; it is a count with no judgement of quality. Each entry has id, entryDate, waypointId, scope, visibility, driveLegId and a body cut to 1000 characters (bodyTruncated is true when cut). With entryId it returns {tripId, entry}: that one entry with its full body.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
entryIdstringOptionalRead only this entry, with its full body
limitintegerOptionalEntries per page, 1 to 50 (default 20)
cursorstringOptionalnextCursor of the previous page. Omit for the first page.

create_logbook_entriesWrites

Create logbook entries

Add 1 to 50 private dated logbook entries (markdown) to one of your trips. Each entry can tag a stop (waypointId) or an imported drive (driveId, which tags the drive's arrival stop with scope "drive"). Entries are created private. Each entry is validated alone: results lists every entry's outcome, its new id or its error. A created entry echoes the tagged stop's recorded lodging (name, type, charger type) as lodging, to compare with its text; an untagged entry carries a warning that it could not be checked. Marks a published journal stale.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
entriesobject[]Required1 to 50 entries to create, in order

update_logbook_entryDestructive

Update logbook entry

Edit one logbook entry: body, entryDate, scope, and/or its stop tag (waypointId, or null to clear it). Omitted fields stay as they are; visibility does not change. Returns the entry with the tagged stop's recorded lodging as lodging, or a warning when it has no stop tag. Marks a published journal stale.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
entryIdstringRequiredId of the entry to change
bodystringOptionalEntry text in markdown, max 10,000 characters
entryDatestringOptionalEntry date as YYYY-MM-DD
waypointIdstring | nullOptionalStop to tag the entry to, or null to clear the tag. Omit to leave the tag unchanged.
scope"stay" | "drive"Optionalstay (default) = about the time at the tagged stop; drive = about the leg that arrived at it (needs a stop tag; the first stop has no inbound drive)

delete_logbook_entryDestructive

Delete logbook entry

Delete one logbook entry from your trip. Cannot be undone. Returns {deleted: true}, or fails with "Entry not found on this trip". Marks a published journal stale.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
entryIdstringRequiredId of the entry to delete

set_logbook_entry_visibilityDestructive

Set logbook entry visibility

Make one logbook entry public or private. A public entry is shown publicly only while its trip is public; tripVisibility in the result is the trip's current visibility. Returns {id, visibility, tripVisibility}. Marks a published journal stale.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
entryIdstringRequiredId of the entry
visibility"private" | "public"Requiredpublic = shown publicly while the trip is public; private = only you see it

read_journalRead-only

Read journal

Read the public trip journal of one of your trips, which is separate from the private logbook. Returns body (live), draftBody (the private pending draft), publishedAt, lastPublishedAt (set on every publish, kept on unpublish, null if never published), source, style, stale (the logbook changed since the last publish) and changedEntryCount (entries created or edited since lastPublishedAt; deletions are not counted, so stale is the reliable change signal).

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips

update_journal_draftDestructive

Update journal draft

Replace the private draft of the public trip journal (markdown). The live body and the publish state do not change, even on a published journal. Each call replaces the whole draft. Returns the journal state.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
bodystringRequiredThe whole draft in markdown, max 10,000 characters. Replaces the previous draft.

set_journal_publishedDestructive

Set journal published

Publish or unpublish the public trip journal. published true makes the pending draft the live public body, sets publishedAt and lastPublishedAt, clears the draft and the stale flag, and records the source as an AI assistant; it fails when there is no draft. published false clears publishedAt only; the body, the draft and lastPublishedAt stay. Returns the journal state.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
publishedbooleanRequiredtrue publishes the pending draft as the live body; false takes the journal offline

read_trip_itineraryRead-only

Read trip itinerary

Read the day-view itinerary of one of your trips: each top-level stop's name, city, state, nights, dates and canAddItems, with its items by day. waypointId reads one stop, a sub-stop included; fromWaypointId and toWaypointId (both inclusive) narrow to a range; upcomingOnly keeps stops not yet arrived at. An unknown stop id fails with "Stop not found on this trip"; upcomingOnly with no upcoming stop returns stops: [] and itemCount: 0. Without a trip startDate no dates are derived and upcomingBasis is "no-start-date". The arrived/upcoming boundary uses the server's UTC day.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
waypointIdstringOptionalRead only this stop
fromWaypointIdstringOptionalFirst stop of the range, inclusive. Omit to start at the first stop.
toWaypointIdstringOptionalLast stop of the range, inclusive. Omit to run through the last stop.
upcomingOnlybooleanOptionalKeep only stops not yet arrived at (default false)

create_itinerary_itemWrites

Create itinerary item

Add a day-view item (activity, dining, sightseeing, note, and more) to a stop with at least one night. Takes no coordinates. An invalid dayOffset, type or title is rejected with the app's own validation message. Returns the created item.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
waypointIdstringRequiredStop to add the item to; it needs at least one night
dayOffsetintegerRequiredDay of the stay, counted from arrival: 0 to 365
type"sightseeing" | "dining" | "activity" | "lodging" | "charging" | "transit" | "other"RequiredItem type: sightseeing, dining, activity, lodging, charging, transit, other
titlestringRequiredShort title for the item
descriptionstring | nullOptionalLonger description
timeOfDaystring | nullOptionalFree-form time, e.g. "9:00am" or "morning"
urlstring | nullOptionalLink, e.g. a listing or reservation page

update_itinerary_itemDestructive

Update itinerary item

Edit a day-view item: title, description, url, timeOfDay, type and/or dayOffset; omitted fields stay as they are and null clears description, url or timeOfDay. toWaypointId moves the item to another stop with at least one night on the same trip, at the end of its day: the moved item gets a new id, previousItemId is the old one, and its approval status and author are kept. Returns {moved, item, previousItemId}. An empty change is rejected.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
itemIdstringRequiredId of the item to change
toWaypointIdstringOptionalMove the item to this stop on the same trip; it needs at least one night
titlestringOptionalShort title for the item
descriptionstring | nullOptionalLonger description, or null to clear it
urlstring | nullOptionalLink, or null to clear it
timeOfDaystring | nullOptionalFree-form time, or null to clear it
type"sightseeing" | "dining" | "activity" | "lodging" | "charging" | "transit" | "other"OptionalItem type: sightseeing, dining, activity, lodging, charging, transit, other
dayOffsetintegerOptionalDay of the stay, counted from arrival: 0 to 365

delete_itinerary_itemDestructive

Delete itinerary item

Delete one day-view item from your trip. Its stop must have at least one night. Cannot be undone. Returns {deleted: true}.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
itemIdstringRequiredId of the item to delete

request_stop_photo_uploadWrites

Request stop photo upload

Step 1 of 2 to attach a photo to a stop on your trip. Returns {uploadId, uploadUrl, method, expiresIn, maxSizeBytes}: a one-time URL valid for 15 minutes. Finishing needs a client that can send an HTTP PUT of the raw image bytes (jpeg, png, webp or heic, up to 10 MB) to uploadUrl with a matching Content-Type header, for example Claude Code; image data does not go through a tool call. The stored photo has its embedded date and location metadata stripped.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
waypointIdstringRequiredStop the photo belongs to

finalize_stop_photo_uploadWrites

Finalize stop photo upload

Step 2 of 2: attach the image sent by HTTP PUT to the uploadUrl of step 1 to the stop. The photo is converted to WebP and stripped of metadata, as in the app; an image over 10 MB decoded, an unknown image type, or a caption over 280 characters is rejected. uploadId expires 15 minutes after step 1 and works once. caption is text the caller writes; the server generates none. Returns {photo}.

FieldTypeRequiredNotes
tripIdstringRequiredId of one of your trips
waypointIdstringRequiredStop the photo belongs to, the same as in step 1
uploadIdstringRequireduploadId returned by step 1
captionstring | nullOptionalCaption, up to 280 characters, written by the caller from the photo. It is also the photo alt text.

Agent2Agent (A2A)

POST /a2a serves the same tools as skills over the A2A protocol, version 1.0, JSON-RPC binding. The agent card is at/.well-known/agent-card.json. Send the headerA2A-Version: 1.0.

  • Calling a skill - sendSendMessage with one data part shaped{"skill": "<skill id>", "arguments": {...}}. The skill id is a tool name from Tools, and the arguments are that tool's input fields. The skill runs before the answer, so the answer is a finished task:TASK_STATE_COMPLETED with the tool's result as one artifact, orTASK_STATE_FAILED with the error text in status.message.
  • Tasks - GetTask and ListTasks return your own tasks for 7 days. CancelTask answers -32002, because every task is already finished. Streaming and push notifications are not supported.
  • Authentication - the same bearer token as/mcp. When you get a token with OAuth, sendresource=https://roadbook.us/mcpon the authorization request. The token is issued for the MCP URL and both endpoints accept it. A request with another resource, or none, is refused withinvalid_target.
  • Errors - a skill that fails (not found, not yours, rejected arguments) answers a TASK_STATE_FAILED task. A missing sign-in or plan answers a JSON-RPC error with code -32000 and the reasonUNAUTHENTICATED orPERMISSION_DENIED. Over the request rate limit, the answer is HTTP 429 withRetry-After and a JSON-RPC error with code -32000 and the reasonRESOURCE_EXHAUSTED. A call stopped by a per-tool limit or the daily lookup limit answers aTASK_STATE_FAILED task that is not stored.

Add a booking to your trip from an email

Your booking confirmation stays in your email. Your own assistant, such as Claude, reads it. Roadbook does not read email. Roadbook keeps the trip: its stops, dates and charging details. It shows you any night left unbooked, or booked at both of two stops in a row, when both stops have booked dates. You decide what to change.

The example uses an invented email: "Sample Inn (synthetic). Your stay is confirmed. Inn. Reference REF-000000. Check-in 2026-11-07. Check-out 2026-11-09. 2 nights." The samples below are shortened to the fields this example uses.

  1. Connect your assistant to Roadbook (see Authentication). Tool calls need an active premium subscription.
  2. Give your assistant the email text. Tell it which trip and which stop the stay belongs to.
  3. Your assistant can call list_trips to get your trips and their ids. Tell it which trip if two share a name.
    {
      "trips": [
        {
          "id": "trip-4132",
          "name": "Autumn cabin trip",
          "startDate": "2026-11-04"
        }
      ]
    }
  4. It calls read_trip with that trip's id to find the stop's id.
  5. If that stop already has lodging, tell your assistant whether to change it. update_stop edits the stop's latest booking. It does not add a second one. This example uses a stop with no lodging yet.
  6. It calls update_stop with the lodging name, type, check-in date, check-out date and reservation reference from the email.
    {
      "tripId": "trip-4132",
      "waypointId": "wp-4132-b",
      "lodgingName": "Sample Inn (synthetic)",
      "lodgingType": "inn",
      "checkIn": "2026-11-07",
      "checkOut": "2026-11-09",
      "reservationRef": "REF-000000"
    }
    Roadbook answers:
    { "updated": true }
  7. It calls read_trip again.
  8. You review the stop and the lodgingBookingIssues list. A gap is a night between two consecutive overnight stops that both have booked dates, with no booking covering it. An overlap is a night booked at both of two consecutive overnight stops. A stop without dates is not checked. Here, the night of 2026-11-06 has no booking. Roadbook changes nothing for you. Tell your assistant what to change, or edit the trip yourself.
    {
      "stops": [
        {
          "id": "wp-4132-a",
          "name": "Death Valley National Park",
          "lodging": [
            {
              "lodgingName": "Sample Motel (synthetic)",
              "checkIn": "2026-11-04",
              "checkOut": "2026-11-06"
            }
          ]
        },
        {
          "id": "wp-4132-b",
          "name": "Gateway Arch National Park",
          "lodging": [
            {
              "lodgingName": "Sample Inn (synthetic)",
              "lodgingType": "inn",
              "checkIn": "2026-11-07",
              "checkOut": "2026-11-09",
              "reservationRef": "REF-000000"
            }
          ]
        }
      ],
      "lodgingBookingIssues": [
        {
          "kind": "gap",
          "previousStopName": "Death Valley National Park",
          "nextStopName": "Gateway Arch National Park",
          "firstNight": "2026-11-06",
          "lastNight": "2026-11-06"
        }
      ]
    }