voyage/documentation/docs/guides/travel_agent.md

Travel Agent (MCP)

Voyage includes a Travel Agent interface exposed through an MCP-compatible HTTP endpoint. This lets external MCP clients read and manage trip itineraries programmatically for authenticated users.

Endpoint

• Default path: api/mcp
• Configurable with: DJANGO_MCP_ENDPOINT

If you run Voyage at https://voyage.example.com, the default MCP URL is:

https://voyage.example.com/api/mcp

Authentication

MCP requests must include a DRF token in the Authorization header:

Authorization: Token <token>

Use a token associated with the Voyage user account that should execute the MCP actions.

Get a token from an authenticated session

Voyage exposes a token bootstrap endpoint for logged-in users:

• GET /auth/mcp-token/

Call it with your authenticated browser session (or any authenticated session cookie flow). It returns:

{ "token": "<token>" }

Then use that token in all MCP requests with the same header format:

Authorization: Token <token>

Available MCP tools

The Voyage MCP server currently exposes these tools:

• list_collections
• get_collection_details
• list_itinerary_items
• create_itinerary_item
• reorder_itinerary

Tool parameters

list_collections

• No parameters.

get_collection_details

• collection_id (required, string UUID): collection to inspect.

list_itinerary_items

• collection_id (optional, string UUID): if provided, limits results to one collection.

create_itinerary_item

Required:

• collection_id (string UUID)
• content_type (location | transportation | note | lodging | visit | checklist)
• object_id (string UUID, id of the referenced content object)

Optional:

• date (ISO date string, required when is_global is false)
• is_global (boolean, default false; when true, date must be omitted)
• order (integer; if omitted, Voyage appends to the end of the relevant scope)

reorder_itinerary

Required:

• items (list of item update objects)

Each entry in items should include:

• id (required, string UUID of CollectionItineraryItem)
• date (ISO date string for dated items)
• order (integer target order)
• is_global (optional boolean; include when moving between global and dated scopes)

End-to-end example flow

This example shows a typical interaction from an MCP client.

1. Connect to the MCP endpoint using your Voyage server URL and token header.
2. Call list_collections to find the trip/collection you want to work with.
3. Call get_collection_details for the selected collection ID to inspect current trip context.
4. Call list_itinerary_items for a specific date or collection scope.
5. Call create_itinerary_item to add a new stop (for example, a location or note) to the itinerary.
6. Call reorder_itinerary to persist the final ordering after insertion.

Example request headers (HTTP transport)

POST /api/mcp HTTP/1.1
Host: voyage.example.com
Authorization: Token <token>
Content-Type: application/json

Example interaction sequence (conceptual)

Client -> list_collections
Server -> [{"id": "6c5d9f61-2f09-4882-b277-8884b633d36b", "name": "Japan 2026"}, ...]

Client -> get_collection_details({"collection_id": "6c5d9f61-2f09-4882-b277-8884b633d36b"})
Server -> {...collection metadata...}

Client -> list_itinerary_items({"collection_id": "6c5d9f61-2f09-4882-b277-8884b633d36b"})
Server -> [...current ordered itinerary items...]

Client -> create_itinerary_item({
  "collection_id": "6c5d9f61-2f09-4882-b277-8884b633d36b",
  "content_type": "location",
  "object_id": "fe7ee379-8a2b-456d-9c59-1eafcf83979b",
  "date": "2026-06-12",
  "order": 3
})
Server -> {"id": "5eb8c40c-7e36-4709-b4ec-7dc4cfa26ca5", ...}

Client -> reorder_itinerary({"items": [
  {
    "id": "5eb8c40c-7e36-4709-b4ec-7dc4cfa26ca5",
    "date": "2026-06-12",
    "order": 0
  },
  {
    "id": "a044f903-d788-4f67-bba7-3ee73da6d504",
    "date": "2026-06-12",
    "order": 1,
    "is_global": false
  }
]})
Server -> [...updated itinerary items...]

Related docs

• Advanced Configuration
• How to use Voyage