Authentication
The Traveler.md MCP server uses OAuth 2.1 with PKCE (S256). Each traveler authorizes a client once; the client receives an access token (short-lived) and a refresh token (long-lived) scoped to that traveler.
Most MCP clients don’t need any of the URLs below: point the client at the server URL (https://mcp.traveler.md/mcp) and it discovers the authorization server automatically via protected-resource metadata and authorization-server metadata . The endpoints are listed for clients that need to be configured by hand.
Endpoints
These endpoints run on connect.traveler.md.
| Purpose | URL |
|---|---|
| Authorization | https://connect.traveler.md/v1/oauth/authorize |
| Token | https://connect.traveler.md/v1/oauth/token |
| Token revocation | https://connect.traveler.md/v1/oauth/revoke |
| Dynamic client registration | https://connect.traveler.md/v1/oauth/register |
| JWKS | https://connect.traveler.md/v1/oauth/jwks.json |
| Authorization-server metadata | https://connect.traveler.md/.well-known/oauth-authorization-server |
| Protected-resource metadata | https://mcp.traveler.md/.well-known/oauth-protected-resource |
Machine-readable declarations
If you are generating a client, read these instead of this page.
| File | What it declares |
|---|---|
| Protected-resource metadata | The authorization server for mcp.traveler.md, and its scopes_supported |
| Authorization-server metadata | Every endpoint above, scopes_supported, and code_challenge_methods_supported |
/openapi.json | OpenAPI 3.1 security scheme naming all seven scopes, and the scope each tool needs |
/.well-known/mcp.json | Server URL, transport, scopes, tools, and both discovery URLs in one document |
The first two are authoritative. Prefer them. The last two are published on this documentation site for agents that start from the docs domain.
You do not need to register a client with us ahead of time. The authorization server supports dynamic client registration at the endpoint above, and most MCP clients register themselves through it automatically as part of the first connection. It also supports client ID metadata documents: a client can use the HTTPS URL of a metadata document it publishes as its client_id and skip registration. Registration needs no authentication, and the token endpoint accepts client_secret_post, client_secret_basic, or no client authentication at all for public clients using PKCE.
Scopes
A client must request the minimum scopes it needs. The consent screen shows the traveler exactly what they’re approving.
| Scope | What it allows |
|---|---|
profile.read | Read your Traveler.md |
profile.create | Create your Traveler.md |
profile.update | Update your Traveler.md |
trip.read | Read your trips |
trip.create | Create new trips |
trip.update | Update and archive your trips |
trip.list | List your trips |
There is no “all scopes” shortcut. Asking for more than you need is a fast way to lose a traveler’s trust. A read-only assistant, for example, only needs profile.read, trip.read, and trip.list.
trip.update covers both editing a trip and archiving it (archive_trip), because archiving is a reversible trip mutation rather than a separate capability. It does not grant deletion. No MCP tool can delete a trip.
Token lifecycle
- Access tokens are JWTs, valid for 15 minutes. Use them in the
Authorization: Bearer <token>header on MCP requests. - Refresh tokens are opaque, valid for 90 days of inactivity. Use the token endpoint to exchange them for new access tokens.
- A refresh token is rotated on every exchange; store the new one and discard the old.
- The inactivity clock resets on every exchange, so a client that refreshes at least once every 90 days is never asked to reconnect for that reason alone.
- A connection is capped at one year in total, counted from the traveler’s original authorization and unaffected by how often the client refreshes. After that the traveler reauthorizes once, and the clock restarts.
Handle the rotated token carefully. If your client discards the new refresh token and retries with the old one, the server treats that as a replayed credential and ends the connection, which costs the traveler a reconnect. Persist the new token before you use the access token that came with it, and don’t run two instances refreshing the same connection at once.
Revoking access
Travelers manage and revoke connections from Connections, which lists every app they’ve authorized. Once a connection is revoked:
- MCP calls fail with an
UNAUTHORIZEDtool error and return no data. - The client must walk the traveler through the OAuth flow again to reconnect.
Revocation and scope narrowing take effect within a minute. The server checks the traveler’s current grant on tool calls and keeps the result for up to 60 seconds. An access token issued before the change loses the removed capability within that minute, before the token’s 15-minute lifetime ends. Do not build a client that depends on a grace window in either direction.
Clients can also call the revocation endpoint themselves when uninstalling.
What we do not collect
The MCP server only sees what the traveler has stored in their Traveler.md and Trip.md. It does not collect:
- Health or medical details and accessibility needs. Every connected agent is instructed not to record them
- Payment card, passport, social security and known traveler numbers. The server rejects a write that contains one
- Booking IDs from third-party systems unless the traveler chose to record them
- Conversation history from the connected client
For privacy specifics and data handling commitments, see Support.