jubnl
c828fca059
- Add OAuth 2.0 client_credentials flow so AI agents and scripts can obtain tokens directly via client_id + client_secret without any browser interaction - New DB column allows_client_credentials on oauth_clients; machine clients skip redirect URI requirement and are forced confidential - New issueClientCredentialsToken() issues access-only tokens (no refresh token, RFC 6749 §4.4) - UI: "Machine client" checkbox in create-client modal, hides redirect URI field, shows indigo badge on existing machine clients - Advertise client_credentials in OAuth discovery document - 8 new integration tests (OAUTH-CC-001–008) - i18n: 4 new keys across all 15 languages - Fix PlaceAvatar: re-fetch photo via API on image_url load failure before falling back to initials - Update MCP wiki docs with new Option B machine client setup guide
3.0 KiB
MCP Overview
TREK includes a built-in Model Context Protocol (MCP) server. MCP is an open standard that lets AI assistants read and modify data in external services through a structured API. When the MCP addon is enabled on your TREK instance, AI clients such as Claude.ai, Claude Desktop, Cursor, VS Code, and others can connect directly to your trips.
What you can do
Once connected, an AI assistant can work with your TREK data in a single conversation:
- Create and update trips, days, and itineraries
- Search for real-world places and add them to your trip
- Build and manage packing lists and to-do items
- Track budgets and expenses across trip members
- Create reservations, transport bookings, and accommodations
- Send collab messages and notes to other trip members
- Mark countries and regions as visited in Atlas
- Log vacation days in Vacay
- Write journey entries across multiple trips
Changes made through MCP are broadcast to all connected clients in real-time — exactly like changes made in the web UI.
Authentication options
| Use case | Method |
|---|---|
| Interactive client (Claude.ai, Cursor, VS Code…) | OAuth 2.1 with browser consent — TREK issues tokens after you approve scopes in a consent screen |
| AI agent or script running unattended | Machine client (client_credentials) — token obtained directly via client_id + client_secret, no browser ever opened |
| Legacy setups | Static API token — deprecated, full access, no scopes |
See MCP-Setup for step-by-step instructions for each method.
Requirements
- MCP addon enabled — an administrator must enable the MCP addon (
mcp) from the Admin Panel before the/mcpendpoint becomes available and the MCP section appears in user settings. APP_URLset — theAPP_URLenvironment variable must be configured to your TREK instance's public URL so that OAuth discovery works correctly. Without it, clients that use OAuth 2.1 cannot complete authentication.
Rate limits and session limits
| Setting | Default | Environment variable |
|---|---|---|
| Requests per minute per user | 300 | MCP_RATE_LIMIT |
| Max concurrent sessions per user | 20 | MCP_MAX_SESSION_PER_USER |
Rate limits are tracked per user–client pair, so each OAuth client has its own independent window. Sessions expire after 1 hour of inactivity.
Endpoint
https://<your-trek-instance>/mcp
If the MCP addon is not enabled, this endpoint returns 403. If authentication fails, it returns 401.
Admin: Enable the MCP addon in Admin-Addons. Set
APP_URLfor OAuth discovery. Revoke tokens and manage OAuth clients from Admin-MCP-Tokens. Adjust rate and session limits withMCP_RATE_LIMITandMCP_MAX_SESSION_PER_USER— see Environment-Variables.
Next steps
- MCP-Setup — connect your AI client
- MCP-Scopes — choose the right permissions
- MCP-Tools-and-Resources — browse available tools