TREK MCP Server Tools and Resources: Complete API and Extension Guide

The TREK MCP server exposes a comprehensive suite of RESTful APIs, WebSocket real-time collaboration, OAuth2 authentication, and a dynamic add-on framework that enables secure, extensible travel-planning functionality.

The TREK MCP (Management Control Plane) server serves as the central backend hub for the TREK travel-planning platform housed in the mauriceboe/TREK repository. It provides a modular micro-service architecture where each capability is presented as a scoped HTTP endpoint or persistent WebSocket channel, allowing client applications to manage trips, users, and geographic data through a unified authentication layer.

Core REST API for Trip Management

The MCP server implements versioned REST endpoints under /api/v1/ that handle CRUD operations for the platform's primary entities. According to the mauriceboe/TREK source code, these endpoints cover trips, members, notes, packing lists, itineraries, and reservations.

Key endpoints include:

• POST /api/v1/trips – Creates a new trip with validated payload parameters.
• GET /api/v1/trips/:id – Retrieves a specific trip's details and associated metadata.
• PUT /api/v1/trips/:id – Updates trip properties with scope-checked authorization.

The business logic for these operations resides in src/services/trip.service.ts, which handles database transactions and validation before returning responses to the Express/Koa routing layer defined in src/server.ts.

Authentication and Scoped JWT Authorization

Security is enforced through an OAuth2/OIDC token flow that issues scoped JWTs for every client request. The authentication handlers in src/auth/* manage the complete lifecycle, including initial login, token refresh, and revocation.

The system supports fine-grained scopes such as trips.read, trips.write, maps.search, and admin, which are embedded in the JWT payload. Every API endpoint validates these scopes via middleware before invoking downstream services.

Token endpoints include:

• /auth/login – Exchanges credentials for an access token.
• /auth/refresh – Rotates expired tokens while maintaining session continuity.
• /auth/logout – Invalidates tokens and clears client sessions.

Real-Time Collaboration via WebSocket

Beyond HTTP, the TREK MCP server provides WebSocket-based synchronization for live trip updates, chat, polls, and itinerary changes. The WebSocket hub is initialized in src/server.ts and exposes ws://<host>/ws for multiplexed connections.

Clients subscribe to channels using naming conventions like trip-{id} or chat-{id}, allowing targeted broadcasts without polling overhead. This architecture ensures that all connected clients receive instantaneous updates when underlying data changes, as documented in the wiki/Real-Time-Collaboration.md reference.

Add-On Framework for Third-Party Extensibility

The MCP server supports a plug-in architecture that allows third-party services to register new endpoints without modifying core code. At startup, the server scans the src/addons/ directory and validates each package's manifest.json file.

Each manifest defines:

• Route prefixes – Mounted under /addons/<name>/.
• Required scopes – Merged into the global JWT validation logic.
• Service hooks – Integration points for background workers and real-time events.

This dynamic loading system enables capabilities like flight-price tracking or weather providers to extend the API surface area while maintaining isolation from core trip management logic.

Map Services and Geographic Operations

Geographic functionality is handled through dedicated services in src/services/map.service.ts. These tools provide integrated map tiles, place search, and route optimization.

Available endpoints include:

• /api/v1/maps/tiles/:z/:x/:y – Proxies map tile requests with caching headers.
• /api/v1/places/search?q=... – Returns geocoded results for itinerary planning.

The service also manages offline map caching strategies, ensuring that mobile clients can access geographic data without persistent connectivity.

Export, Notifications, and Administrative Tools

The MCP server provides utility endpoints for data portability and system management. PDF and CSV export capabilities are available via GET /api/v1/trips/:id/export?format=pdf|csv, handled by background workers to prevent blocking the main event loop.

Push notifications are managed through a centralized hub that dispatches via Firebase Cloud Messaging and Apple Push Notification service (APNs). The notification service uses scoped endpoints at POST /api/v1/notifications and processes delivery queues asynchronously via Bull or RabbitMQ workers.

For system administrators, the Admin Panel exposes routes under /admin/* protected by the admin scope. This interface allows management of user accounts, add-on registry, encryption key rotation, and audit log review via endpoints like /api/v1/audit and /api/v1/keys/rotate.

System Architecture and Request Flow

Understanding how these tools interact requires examining the request lifecycle implemented in mauriceboe/TREK:

1. Authentication Layer – Clients obtain scoped JWTs from /auth/login, which contain permissions for specific resources.
2. Authorization Middleware – src/server.ts applies scope validation before routing requests to micro-services.
3. Service Routing – Validated requests are forwarded to domain-specific handlers like src/services/trip.service.ts or src/services/map.service.ts.
4. Add-On Integration – The add-on loader dynamically registers third-party routes from src/addons/ and merges their scope requirements into the validation chain.
5. Real-Time Broadcast – After successful mutations, the WebSocket hub broadcasts updates to subscribed channels, ensuring client synchronization.
6. Background Processing – Tasks such as PDF generation, email dispatch, and encryption key rotation are offloaded to worker processes to maintain API responsiveness.

Practical Code Examples

The following JavaScript examples demonstrate how to authenticate and interact with the TREK MCP server tools.

Obtain an Access Token:

import fetch from 'node-fetch';

const tokenRes = await fetch('https://mcp.trek.example.com/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'my-client',
    client_secret: '********',
    grant_type: 'client_credentials',
    scope: 'trips.read trips.write maps.search'
  })
});
const { access_token } = await tokenRes.json();

Create a Trip via Core API:

await fetch('https://mcp.trek.example.com/api/v1/trips', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Summer Europe 2027',
    startDate: '2027-06-15',
    endDate: '2027-07-05'
  })
});

Consume an Add-On Service:

await fetch('https://mcp.trek.example.com/addons/flight-tracker/api/v1/flights?origin=NYC&dest=PAR', {
  headers: { Authorization: `Bearer ${access_token}` }
});

Subscribe to Real-Time Updates:

import WebSocket from 'ws';

const ws = new WebSocket('wss://mcp.trek.example.com/ws');
ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'subscribe', channel: 'trip-123' }));
});
ws.on('message', data => console.log('Update:', JSON.parse(data)));

Summary

• TREK MCP Server provides a centralized backend for travel-planning with RESTful APIs, WebSocket collaboration, and OAuth2 security.
• Core tools include trip CRUD operations, map services, and export functionality, implemented in src/services/trip.service.ts and src/services/map.service.ts.
• Extensibility is achieved through a dynamic add-on framework that scans src/addons/ and validates manifest.json files at runtime.
• Authentication relies on scoped JWTs issued via /auth/login and validated by middleware in src/auth/*.
• Real-time features use WebSocket channels multiplexed through the hub configured in src/server.ts.
• Administrative controls include audit logging, key rotation, and an admin panel protected by the admin scope.

Frequently Asked Questions

What authentication flow does the TREK MCP server use?

The TREK MCP server implements an OAuth2/OIDC token flow that issues scoped JWTs. Clients authenticate against /auth/login to receive access tokens containing specific permissions like trips.read or admin, which are validated by middleware on every subsequent request.

How do add-ons extend the MCP server functionality?

Add-ons are discovered dynamically from the src/addons/ directory at startup. Each add-on provides a manifest.json that defines its route prefix, required scopes, and service hooks. The server mounts these under /addons/<name>/ and merges their scope requirements into the global authorization chain without requiring core code changes.

Which real-time protocols are supported for trip collaboration?

The MCP server supports WebSocket-based real-time collaboration through a persistent connection at /ws. This protocol enables multiplexed channels (e.g., trip-{id}, chat-{id}) for live synchronization of notes, polls, and itinerary updates across all connected clients.

Where are the core service implementations located in the codebase?

Core business logic resides in src/services/trip.service.ts for trip management and src/services/map.service.ts for geographic operations. The main server configuration, including routing and WebSocket initialization, is found in src/server.ts, while authentication handlers are grouped under src/auth/*.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}