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

> Explore TREK MCP server tools and resources including RESTful APIs, WebSocket, OAuth2, and add-on framework for extensible travel planning. Access the complete API and extension guide.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: api-reference
- Published: 2026-07-03

---

**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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/src/services/trip.service.ts) or [`src/services/map.service.ts`](https://github.com/mauriceboe/TREK/blob/main/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:**

```javascript
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:**

```javascript
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:**

```javascript
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:**

```javascript
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`](https://github.com/mauriceboe/TREK/blob/main/src/services/trip.service.ts) and [`src/services/map.service.ts`](https://github.com/mauriceboe/TREK/blob/main/src/services/map.service.ts).
- **Extensibility** is achieved through a dynamic add-on framework that scans `src/addons/` and validates [`manifest.json`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/src/services/trip.service.ts) for trip management and [`src/services/map.service.ts`](https://github.com/mauriceboe/TREK/blob/main/src/services/map.service.ts) for geographic operations. The main server configuration, including routing and WebSocket initialization, is found in [`src/server.ts`](https://github.com/mauriceboe/TREK/blob/main/src/server.ts), while authentication handlers are grouped under `src/auth/*`.