MCP Integration

TREK includes a built-in Model Context Protocol (MCP) server that lets AI assistants — such as Claude Desktop, Cursor, or any MCP-compatible client — read and modify your trip data through natural language.

Note: MCP is an addon that must be enabled by an admin in Admin Panel → Addons before it becomes available.

How it Works

1. You connect an AI assistant (e.g. Claude Desktop) to your TREK instance
2. You write something like: "Plan me a week in Kyoto with hotels, budget, and packing list"
3. The AI creates everything directly in TREK — trips, places, reservations, budget, packing, notes
4. Changes appear instantly in your browser via real-time WebSocket sync

Setup

1. Enable the MCP addon (admin)

Go to Admin Panel → Addons and enable MCP. Until enabled, the /mcp endpoint returns 403 Forbidden and the MCP section does not appear in user settings.

2. Create an API token

Once MCP is enabled, go to Settings → MCP Configuration:

1. Click Create New Token
2. Give it a descriptive name (e.g. "Claude Desktop", "Work laptop")
3. Copy the token immediately — it is shown only once and cannot be recovered

Each user can create up to 10 tokens.

3. Configure your MCP client

Claude Desktop (recommended)

Edit your config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the mcpServers section (merge with any existing config):

{
  "mcpServers": {
    "trek": {
      "command": "C:\PROGRA~1\nodejs\npx.cmd",
      "args": [
        "mcp-remote",
        "https://your-trek-instance.com/mcp",
        "--header",
        "Authorization: Bearer trek_your_token_here"
      ]
    }
  }
}

Windows: Use C:\PROGRA~1\nodejs\npx.cmd instead of npx to avoid issues with spaces in the Program Files path.

macOS/Linux: You can use npx directly as the command.

Restart Claude Desktop completely (quit from system tray, then reopen).

Claude Code (CLI)

claude mcp add trek -- npx mcp-remote https://your-trek-instance.com/mcp --header "Authorization: Bearer trek_your_token_here"

Cursor / Other IDEs

Consult your IDE's MCP documentation — most support a similar JSON config with command + args.

What the AI Can Do

Resources (read-only) — 14 resources

Resource	Description
Trips	All trips you own or are a member of
Trip Detail	Single trip with metadata
Days	Days with assigned places
Places	All places/POIs in a trip
Budget	Expense items
Packing	Packing checklist
Reservations	Flights, hotels, restaurants, etc.
Day Notes	Notes for specific days
Accommodations	Hotels with check-in/out details
Members	Trip owner and collaborators
Collab Notes	Shared collaborative notes
Categories	Available place categories
Bucket List	Personal travel bucket list
Visited Countries	Countries marked in Atlas

Tools (read-write) — 34 tools

Area	Tools
Trips	List, create, update, delete trips
Places	Create, update, delete places with coordinates, categories, notes
Day Planning	Assign places to days, reorder, set times, update day titles
Reservations	Create/update/delete bookings (flights, hotels, trains, restaurants, etc.)
Budget	Create, update, delete expense items
Packing	Create, update, toggle, delete packing items
Day Notes	Create, update, delete notes with time labels and icons
Collab Notes	Create, update, delete shared notes with categories and colors
Bucket List	Add/remove destinations
Atlas	Mark/unmark countries as visited
Summary	get_trip_summary loads everything about a trip in one call

Example

Here is a real example of what MCP can do. A single prompt to Claude Desktop:

"Plan a week-long trip to Kyoto, Japan, arriving April 5 and leaving April 11. It's cherry blossom season so keep that in mind. Research what's worth visiting, find a hotel, create the trip in TREK with all places, daily itinerary, hotel reservation, restaurant bookings, budget in CHF, packing list, and practical tips as a pinned collab note."

Result: Claude created a complete trip with 20+ places, day-by-day itinerary with times, hotel reservation linked to accommodation days, restaurant bookings, a full budget, packing list, and a pinned note with transport/etiquette tips — all visible instantly in TREK.

Limitations

Limitation	Details
Admin activation required	MCP must be enabled by an admin before any user can access it
Per-user scoping	Each session is scoped to the authenticated user — you can only access trips you own or are a member of
No image uploads	Cover images cannot be set through MCP — use the web UI
Rate limiting	60 requests per minute per user
Session limits	Maximum 5 concurrent MCP sessions per user, 1-hour inactivity timeout
Token limits	Maximum 10 API tokens per user
Demo mode	All write operations are blocked in demo mode

Security

• Tokens are stored as SHA256 hashes — the raw token is shown only once at creation
• Token deletion immediately revokes all active MCP sessions for that user
• All operations respect the user's existing permissions (trip ownership/membership)
• Admins can view and revoke tokens for all users in Admin Panel → MCP Tokens
• Changes made through MCP are broadcast to all connected browser clients in real-time

Compatible Clients

Any MCP client that supports Streamable HTTP transport with custom auth headers:

• Claude Desktop (Anthropic)
• Claude Code (CLI)
• Cursor (IDE)
• Windsurf (IDE)
• VS Code + Copilot (with MCP extension)
• Continue.dev (Open Source)
• Cline (VS Code Extension)

Troubleshooting

"Server disconnected" / "transport closed unexpectedly"

Windows — spaces in path: If you see Der Befehl "C:\Program" ist entweder falsch geschrieben, the space in C:\Program Files is breaking the command. Use the 8.3 short path:

"command": "C:\PROGRA~1\nodejs\npx.cmd"

instead of "command": "npx".

Missing Bearer prefix: Make sure your Authorization header includes Bearer:

"Authorization: Bearer trek_your_token_here"

Not just "Authorization: trek_your_token_here".

"403 Forbidden"

The MCP addon is not enabled. Ask your admin to enable it in Admin Panel → Addons → MCP.

"401 Access token required"

• Your token may be invalid or revoked — create a new one in Settings
• Check that the Authorization: Bearer header is correctly formatted
• Make sure there are no extra spaces or line breaks in the token

"429 Too many requests"

You've exceeded the rate limit (60 requests/minute). Wait a moment and try again. If the AI is making many rapid changes, ask it to slow down or batch operations.

"Session limit reached"

You have 5 active MCP sessions. Close unused clients or wait for idle sessions to expire (1 hour timeout).

Token not showing in Settings

Make sure the MCP addon is enabled by an admin. The MCP Configuration section only appears in user settings when the addon is active.

Changes not appearing in the browser

Verify your WebSocket connection is working (see Real-Time Sync). MCP changes are broadcast via WebSocket — if /ws is blocked by your reverse proxy, changes won't sync in real-time but will appear on page reload.

Node.js / npx not found

mcp-remote requires Node.js installed on the machine running Claude Desktop. Install it from nodejs.org (LTS recommended). After installation, restart Claude Desktop.