AI integration · Model Context Protocol · planned

Roadbook MCP

Give AI agents a standard way to create and validate portable travel itineraries. The Roadbook format is designed to be authored by AI agents; an official Model Context Protocol server is planned so that assistants can create, validate, repair and update roadbooks natively. It will be implemented and hosted on the official player side — this page is a design note, and nothing described here is available yet.

Status: planned, not released. Do not configure or advertise a Roadbook MCP endpoint yet. Today, agents use the format directly: llms.txt / llms-full.txt, the JSON Schema, the validator library and the hosted POST /api/validate endpoint cover generation and validation without MCP; a valid file is then opened in roadbook.plus.

status planned · not available hosted by roadbook.plus (official player) transport HTTP (remote) spec target ≥ 1.0

What works today, without MCP#

The format is LLM-friendly by construction: point any capable model at the canonical URLs of the specification and the JSON Schema and ask it to produce a .roadbook.json. Then check the output with the validator — its path + message errors are designed to be pasted back to the model for self-correction. A complete, copy-ready prompt lives on the AI page.

# A working prompt pattern
"Read the Roadbook format specification at
   https://roadbookformat.org/spec.html
 and its JSON Schema at
   https://roadbookformat.org/roadbook.schema.json
 Generate a 3-day family trip to Lisbon as a single
 valid .roadbook.json file, format version 1.2.
 Output only the JSON."

Agents and crawlers can also start from /llms.txt, which lists these URLs.

Planned format-level tools#

Stateless tools about the format, reusing the reference validator — no travel information is invented by the server, its responsibility is structure and validation:

create_roadbook(input): Builds a valid skeleton (trip metadata, members, empty days for each date) from structured input — no places or activities are invented.
validate_roadbook({ roadbook }): Runs the reference validator; returns { valid, errors, warnings } with path + message entries; writes nothing.
repair_roadbook({ roadbook, errors }): Applies deterministic fixes where possible (ids, ordering, indexes, formats) and returns the corrected document plus what remains for the model to fix.

// validate_roadbook — input
{ "roadbook": { "formatVersion": "1.2", "id": "…", … } }
// output
{ "valid": false,
  "errors": [ { "path": "$.days[2].date", "message": "Day 2026-10-16 falls outside the trip period (…)" } ],
  "warnings": [] }

Possible later: merge_roadbooks, convert_itinerary_to_roadbook, summarize_roadbook.

Planned trip-level tools (hosted trips)#

For trips hosted by the official player, the server would additionally expose a small, safe tool set — mirroring the guarantees players rely on (validation before write, optimistic version locking, backup before mutation):

get_trip(): Returns the current roadbook (media stripped to lightweight references).
validate_trip(trip): Runs the official validator; returns { ok, errors, warnings } without writing anything.
upsert_entities(changes, baseVersion): Merges complete entities by id (days, bookings, checklists, contacts, logistics, apps). Rejected with a conflict if the trip changed since baseVersion — no silent overwrite.
remove_entities(ids, baseVersion): Removes entities by id, same version lock.
upload_media(dataUrl): Stores an image or PDF (ticket, voucher…) and returns the URL to reference in the trip file — media never lives inline in the JSON.
restore_backup(): Reverts to the automatic pre-mutation backup.

Design principles#

Principle	Consequence
`validate-first`	Every write path runs the official validator; an agent cannot persist an invalid roadbook.
`version-locked`	Mutations carry the version they were computed against; concurrent edits surface as explicit conflicts, never silent overwrites.
`whole-entity merge`	Changes are complete entities merged by `id` — the same semantics as the spec, easy for a model to reason about.
`media out-of-band`	Files go through `upload_media`; the JSON only carries references, keeping context windows and sync payloads small.
`capability tokens`	Authentication mirrors player capabilities: an edit token is required for any mutating tool.

Planned client configuration#

Not available yet. Target shape once released — a remote HTTP server, one entry per trip, the edit token carried as a bearer credential:

{
  "mcpServers": {
    "roadbook": {
      "type": "http",
      "url": "https://mcp.roadbookformat.org/trips/<trip-id>",
      "headers": { "Authorization": "Bearer <edit-token>" }
    }
  }
}

Hostname, path and token scheme are indicative and may change before release.

Status & feedback#

The server is not released yet — the tool surface above is the design target, validated against a production player. Installation and configuration instructions will be published here once the implementation exists. If you are building a player or generator and want to align on the MCP surface, or if you think a tool is missing, get in touch through the viewers page or open a discussion once the public repository is available. See also integrations → agents.