Developer

MCP server

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:

Connecting Claude to your trips
YouIn Claude, go to Settings → Connectors → Add custom connector and enter https://constellations.li/api/mcp.
YouClaude opens a Constellations sign-in page; approve the connection while signed in to your account.
YouAsk away: "when do I land?", "who's in Lisbon in June?", "what's still on my packing list?".
AutomaticClaude calls the tools below on your behalf, seeing exactly what the account sees in the browser and nothing more.

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:

ToolReturns
get_profileAccount basics: name, email, timezone, location
get_settingsPreferences: reporting currency, storage + attachment auto-save, notification defaults, home city/airport, and jet-lag settings
get_jetlag_planThe jet-lag plan for the current/next qualifying trip: day-by-day wake/bed schedule, or a nudge to enable it
list_my_tripsTrip headers you own or are on, with filters
get_tripFull 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_itemA single item in detail, with the same live leg detail and its comments
get_trip_weatherForecasts along a trip
list_trip_attachmentsFiles on a trip, with access-gated URLs
list_trip_expensesThe trip's expense ledger: splits, receipts, categories, tax, guests, line items, and work flags. Money in (moneyIn: true) carries negative amounts
list_trip_settlementsWho-owes-whom after netting
list_my_workThe work accounts you belong to, and your role
get_work_expensesYour own business-travel spend in a work account
list_trip_checklistsA trip's checklists: a tree of items (a node with children is a group), with ids
list_checklist_templatesYour reusable checklist templates (own + shared), with per-day/qty/max settings
list_my_constellationsGroups you're in
get_constellationOne group: members, shared trips and the latest comments
list_contactsEveryone you're connected to, by source (via: "friends" for friends only)
list_contact_tripsVisible trips a contact or friend is on (via: "friends" for what's shared through your friends list)
list_eventsWhat 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_locationsWhere you and everyone you can see are, now or at a given moment
list_pending_decisionsWhat's waiting for you to accept or decline: expenses from receipts, booking changes, friend requests, disruptions
get_local_timeThe 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_distanceHow 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_currencyAn amount in another currency, at today's rate or a given day's
list_commentsComments 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_signalsYour signals feed, newest first (archived: true for dismissed ones)
get_travel_profileYour 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_changesOpen proposals / pending confirmations
list_help_docsThe help-centre table of contents
search_help_docsFull-text search across help articles
get_help_docOne 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:

ToolDoes
create_checklistStart a new checklist on a trip, with its items (nested, with quantities) and any of your saved templates in the same call
add_checklist_itemAdd an item, optionally nested under another (parentId)
update_checklist_itemRename an item, change its quantity, tick it off (or untick it), or say you'll bring it
delete_checklist_itemRemove an item (and anything nested under it)
delete_checklistDelete a whole checklist (owner-only)
create_checklist_templateCreate a reusable template (items tree + per-day/max + sharing)
update_checklist_templateEdit a template, optionally pushing the change into upcoming trips that used it
delete_checklist_templateDelete a template you own or admin
apply_checklist_templateDrop a template's items into a trip's checklist
update_tripRename a trip (or clear its name) or set its planned first and last days
update_trip_itemChange a booking's name, times, places, note, booking reference or seat
update_expenseChange an expense's label, amount, currency, date, notes or category
move_trip_itemMove a booking to another trip, with its files
move_expenseMove an expense to another trip
move_attachmentMove a trip-level file to another trip
move_checklistMove a checklist, with its items, to another trip
resolve_pending_decisionAccept or decline something from list_pending_decisions
create_tripStart an empty trip, with an optional name and planned dates
add_trip_itemAdd a leg, stay or event to a trip (or to a new trip). A flight is looked up and tracked as usual
add_expenseAdd an expense split equally between people on the trip; moneyIn records a refund or gift instead
record_settlementRecord that someone paid someone back
add_trip_todoAdd a to-do to a trip, with an optional note and reminder
update_trip_todoChange a to-do, tick it off or untick it, or set or clear its reminder
set_leg_followFollow or unfollow a leg
set_pickupOffer to pick someone up off a leg, from a named place, or cancel
post_commentComment on a trip, booking or group. "@Name" mentions someone (only they're told); "#Title" links a booking; replyToId answers a comment
edit_commentChange a comment you wrote
remove_commentDelete your own comment, or remove someone else's as the trip's owner or editor or the group's admin
react_to_commentAdd or take off a reaction
report_disruptionReport 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).

Webhooks are the push-shaped counterpart to this pull-shaped API. See Webhooks.