Constellations exposes a Model Context Protocol server so AI assistants can read your travel data with your permission. Connect Claude (or any MCP client) and it can answer "when do I land?" or "who's in Lisbon in June?" from your actual trips.
- Endpoint:
https://constellations.li/api/mcp - Transport: Streamable HTTP (JSON responses)
- Capability: read, plus a set of write tools when the connection was granted them (see below)
Connecting from Claude
The worked example, using claude.ai custom connectors:
https://constellations.li/api/mcp.Where Claude shows interactive connectors (the web and the desktop app), asking about one trip draws a trip card beside the answer: its dates, a map of the route, what's booked in order, who's going, and a button that opens the trip in Constellations. The card shows only what the answer already had, and loads nothing from anywhere else. Apps that don't draw cards get the same answer as text.
Under the hood this is a standard OAuth 2.0 authorization-code flow with PKCE and dynamic client registration; most MCP clients handle it automatically. Access tokens are short-lived (about an hour) and refresh silently.
The consent page states what the app will be able to do, and that is what the connection can do. An app that asks only to read is offered the read tools; one granted read and edit is offered the write tools further down as well. An app that does not say what it wants is offered both, and the page says so before anything is approved. Connections approved before v0.1091 stay read-only; disconnect and reconnect to grant edits.
Connecting anything else
For scripts and clients that don't speak OAuth, create a personal access token under Settings → Custom connections and send it as a bearer token:
Authorization: Bearer ctok_…
The token value is shown once at creation. Revoke any token from the same page; revocation is immediate. Resetting your password, or signing out everywhere, revokes every token and connected app at once.
What's exposed
Thirty read tools:
| Tool | Returns |
|---|---|
get_profile | Account basics: name, email, timezone, location |
get_settings | Preferences: reporting currency, storage + attachment auto-save, notification defaults, home city/airport, and jet-lag settings |
get_jetlag_plan | The jet-lag plan for the current/next qualifying trip: day-by-day wake/bed schedule, or a nudge to enable it |
list_my_trips | Trip headers you own or are on, with filters |
get_trip | Full trip detail: legs (with live times, including when a flight left and reached the gate beside its takeoff and landing, the delay measured at the gate, gate and terminal, the airline operating a codeshare, pickups and any disruption with its options), stays, events, participants, open to-dos and bookings still to make, and the latest comments |
get_trip_item | A single item in detail, with the same live leg detail and its comments |
get_trip_weather | Forecasts along a trip |
list_trip_attachments | Files on a trip, with access-gated URLs |
list_trip_expenses | The trip's expense ledger: splits, receipts, categories, tax, guests, line items, and work flags. Money in (moneyIn: true) carries negative amounts |
list_trip_settlements | Who-owes-whom after netting |
list_my_work | The work accounts you belong to, and your role |
get_work_expenses | Your own business-travel spend in a work account |
list_trip_checklists | A trip's checklists: a tree of items (a node with children is a group), with ids |
list_checklist_templates | Your reusable checklist templates (own + shared), with per-day/qty/max settings |
list_my_constellations | Groups you're in |
get_constellation | One group: members, shared trips and the latest comments |
list_contacts | Everyone you're connected to, by source (via: "friends" for friends only) |
list_contact_trips | Visible trips a contact or friend is on (via: "friends" for what's shared through your friends list) |
list_events | What happened or is due in a time window, across every trip you can see: departures, arrivals, check-ins and events (kinds to pick which, people or who to pick whose) |
list_people_locations | Where you and everyone you can see are, now or at a given moment |
list_pending_decisions | What's waiting for you to accept or decline: expenses from receipts, booking changes, friend requests, disruptions |
get_local_time | The time now, or at a given moment, for a place (a city, an airport code, or a country), a person, or you: the local time, the offset, how far ahead or behind it is, and, for a city or airport match, a place id for showing it as a card; a country spanning more than one zone returns just its name, and Connie asks which city |
get_distance | How far apart two places are: the straight-line distance, and the drive (time and road distance) when there's a road, optionally for a departure time |
convert_currency | An amount in another currency, at today's rate or a given day's |
list_comments | Comments on a trip (with its linked trips' and bookings'), a booking or a group, newest first, with who can be mentioned and which bookings can be linked |
list_signals | Your signals feed, newest first (archived: true for dismissed ones) |
get_travel_profile | Your personal documents and their dates, passport country and expiry, loyalty programmes, and seat and meal preferences. Passport, Known Traveller and redress numbers and passport scans are never included |
list_recent_changes | Open proposals / pending confirmations |
list_help_docs | The help-centre table of contents |
search_help_docs | Full-text search across help articles |
get_help_doc | One help article in full |
And twenty-six write tools, for a personal access token or a connection granted edits, so an assistant can keep packing lists and templates up to date, add and fix a trip's details, bookings, expenses and to-dos, and arrange pickups, as well as reading them:
| Tool | Does |
|---|---|
create_checklist | Start a new checklist on a trip, with its items (nested, with quantities) and any of your saved templates in the same call |
add_checklist_item | Add an item, optionally nested under another (parentId) |
update_checklist_item | Rename an item, change its quantity, tick it off (or untick it), or say you'll bring it |
delete_checklist_item | Remove an item (and anything nested under it) |
delete_checklist | Delete a whole checklist (owner-only) |
create_checklist_template | Create a reusable template (items tree + per-day/max + sharing) |
update_checklist_template | Edit a template, optionally pushing the change into upcoming trips that used it |
delete_checklist_template | Delete a template you own or admin |
apply_checklist_template | Drop a template's items into a trip's checklist |
update_trip | Rename a trip (or clear its name) or set its planned first and last days |
update_trip_item | Change a booking's name, times, places, note, booking reference or seat |
update_expense | Change an expense's label, amount, currency, date, notes or category |
move_trip_item | Move a booking to another trip, with its files |
move_expense | Move an expense to another trip |
move_attachment | Move a trip-level file to another trip |
move_checklist | Move a checklist, with its items, to another trip |
resolve_pending_decision | Accept or decline something from list_pending_decisions |
create_trip | Start an empty trip, with an optional name and planned dates |
add_trip_item | Add a leg, stay or event to a trip (or to a new trip). A flight is looked up and tracked as usual |
add_expense | Add an expense split equally between people on the trip; moneyIn records a refund or gift instead |
record_settlement | Record that someone paid someone back |
add_trip_todo | Add a to-do to a trip, with an optional note and reminder |
update_trip_todo | Change a to-do, tick it off or untick it, or set or clear its reminder |
set_leg_follow | Follow or unfollow a leg |
set_pickup | Offer to pick someone up off a leg, from a named place, or cancel |
post_comment | Comment on a trip, booking or group. "@Name" mentions someone (only they're told); "#Title" links a booking; replyToId answers a comment |
edit_comment | Change a comment you wrote |
remove_comment | Delete your own comment, or remove someone else's as the trip's owner or editor or the group's admin |
react_to_comment | Add or take off a reaction |
report_disruption | Report a problem with a leg |
Get the checklistId / nodeId these need from
list_trip_checklists, and the templateId from
list_checklist_templates. Write tools run under the same
permissions as the app: anyone on the trip can add and tick items on
a Shared checklist and say they'll bring something; a Visible or
Private checklist is its owner's to change; only a checklist's owner
(or the trip's owner) can delete it;
templates are editable by their owner or a sharing constellation's
admin. update_trip, update_trip_item and update_expense need
edit access to the trip. Adding bookings, expenses, settlements and
to-dos needs edit access to the trip too; following a leg or picking
someone up needs the same access as the app's buttons, and an
expense's payer and everyone it's split with must be on the trip.
Anything more than one person can edit
names the value it replaces: each change to a trip, booking, expense
or checklist item, and a template update (by the version from
list_checklist_templates). If it has changed since the assistant
last read it, nothing is changed and the reply says what it is now.
Ticking an item off is a plain set. Only a booking's owner can change it, as in the app,
and a flight's number, airline and airports stay as they are. A new amount is only accepted for an expense split
equally, and the shares are worked out again; one split by hand is
changed in the app. Every call is recorded in the account's audit log, the same
as a read.
Scoping: you, exactly
The MCP layer has no permissions model of its own. Every tool calls the same data layer as the web app, authenticated as you. An assistant sees precisely what you'd see in the browser: trips others shared with you appear with the same field-level visibility filtering, private fields stay hidden, and nothing is elevated. If you can't see it on the site, neither can your assistant.
That rule decides the tool list, too. The account that operates
Constellations has extra tools on a separate address,
/api/mcp/operator: the Help & feedback queue, the service's health
and activity logs, account lookup, and a read-only view of what a
given account sees, used to diagnose reports. That address answers
only the operator's account: a token belonging to anyone else is
refused, and the check is made against the account on every request
rather than baked into the token. The read-only view can't change
anything, and each use is recorded in the audit trail under the
account viewed.
Requests are rate-limited per account (generous for conversational
use; a runaway agent loop will hit 429s with a Retry-After).