156 lines
4.2 KiB
Markdown
156 lines
4.2 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
https://voyage.example.com/api/mcp
|
|
```
|
|
|
|
## Authentication
|
|
|
|
MCP requests must include a DRF token in the `Authorization` header:
|
|
|
|
```text
|
|
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:
|
|
|
|
```json
|
|
{ "token": "<token>" }
|
|
```
|
|
|
|
Then use that token in all MCP requests with the same header format:
|
|
|
|
```text
|
|
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)
|
|
|
|
```http
|
|
POST /api/mcp HTTP/1.1
|
|
Host: voyage.example.com
|
|
Authorization: Token <token>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
### Example interaction sequence (conceptual)
|
|
|
|
```text
|
|
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](../configuration/advanced_configuration.md)
|
|
- [How to use Voyage](../usage/usage.md)
|