# What Is MCP in TREK? Enabling AI Assistant Integration with Claude and Cursor

> Discover MCP in TREK, a protocol enabling AI assistant integration. Learn how it exposes trip data as an API for Claude and Cursor via JSON-RPC and OAuth.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: internals
- Published: 2026-07-01

---

**MCP (Model Context Protocol) in TREK is a built-in add-on server that exposes the trip-planning data model as a structured, tool-driven API, allowing AI assistants like Claude Desktop and Cursor to read and modify itineraries through OAuth-secured JSON-RPC endpoints.**

TREK, an open-source travel planning platform developed by `mauriceboe/TREK`, implements **MCP (Model Context Protocol)** to transform its business logic into a programmable interface for large language models. This protocol enables LLMs to invoke specific tools—such as creating places, managing budgets, or querying trip summaries—while maintaining strict data integrity and permission controls through scoped authentication.

## What Is MCP in TREK?

**MCP** stands for **Model Context Protocol**, a standardized protocol that TREK implements as an optional add-on module. When enabled by an administrator via the Admin Panel, the MCP server mounts at the `/mcp` endpoint and registers two distinct interface types:

- **Resources**: Read-only URIs such as `trek://trips` or `trek://places/{id}` that provide structured data snapshots.
- **Tools**: Writeable operations like `create_place`, `assign_place_to_day`, and `create_budget_item` that mutate application state.

In [`src/mcp/index.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/index.ts), the server initializes through an `McpServer` instance that aggregates registrations from [`src/mcp/resources.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/resources.ts) and the `src/mcp/tools/` directory:

```typescript
// src/mcp/index.ts (excerpt)
export const mcps = new McpServer({
  resources: registerResources,
  tools: registerTools,
});

```

This architecture ensures that all AI-driven operations execute through TREK's existing business logic layer, preventing unauthorized data manipulation while exposing a consistent API surface.

## How MCP Authentication and Security Works

TREK's MCP implementation enforces **OAuth 2.1** as the primary authentication mechanism, with optional legacy support for static `trek_` tokens. The security model operates through automatic discovery endpoints and granular scopes:

1. **Discovery**: Clients locate the MCP endpoint via `/.well-known/oauth-protected-resource/mcp` and authorization server metadata at `/.well-known/oauth-authorization-server`, implemented in [`src/mcp/oauthProvider.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/oauthProvider.ts).

2. **Scope Enforcement**: The system defines specific capabilities such as `trips:read`, `places:write`, and `budget:write` in [`src/mcp/scopes.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/scopes.ts). Each tool validates these scopes before execution, ensuring AI clients receive only the permissions explicitly granted by the user.

3. **Session Management**: [`src/mcp/sessionManager.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/sessionManager.ts) tracks active connections, supports token revocation, and enforces per-client rate limits to prevent resource exhaustion.

When an AI client connects, it receives a short-lived access token prefixed with `trekoa_` that must accompany every request in the `Authorization: Bearer` header.

## Configuring Claude Desktop and Cursor for TREK MCP

AI assistants including **Claude Desktop**, **Cursor**, and other MCP-compatible clients integrate with TREK using the `mcp-remote` helper package. This Node.js utility handles OAuth discovery, dynamic client registration, and token lifecycle management automatically.

### Claude Desktop Configuration

To connect Claude Desktop to a TREK instance, add the following configuration to your Claude Desktop settings:

```json
{
  "mcpServers": {
    "trek": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-trek-instance.com/mcp"
      ]
    }
  }
}

```

Upon saving, `mcp-remote` initiates the OAuth flow: it fetches the well-known endpoints, opens a browser window for user consent, and stores the resulting access token for the session. The AI assistant then gains access to the specific tools and resources authorized by the selected scopes.

### Integration Flow Step-by-Step

1. **Initiation**: The user starts `npx mcp-remote https://your-trek-instance.com/mcp`.
2. **Discovery**: The helper queries `/.well-known/oauth-protected-resource/mcp` to locate the MCP endpoint.
3. **Authorization**: It then fetches `/.well-known/oauth-authorization-server` to obtain metadata and redirects the user to TREK's consent screen.
4. **Consent**: The user selects required scopes (e.g., `trips:read`, `places:write`) and approves the connection.
5. **Token Issuance**: The client receives a `trekoa_` access token used for subsequent `Authorization: Bearer` headers.
6. **Tool Invocation**: The AI assistant can now call methods like `get_trip_summary` or `create_and_assign_place` via JSON-RPC over HTTP.

## Practical MCP Tool Usage Examples

Once authenticated, AI assistants interact with TREK through JSON-RPC 2.0 requests sent to the `/mcp` endpoint.

### Reading Trip Summaries

To fetch a denormalized snapshot of a trip, the client invokes the `get_trip_summary` tool defined in [`src/mcp/tools/trips.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/tools/trips.ts):

```typescript
import fetch from 'node-fetch';

const MCP_URL = 'https://your-trek-instance.com/mcp';
const ACCESS_TOKEN = 'trekoa_…';

async function getTripSummary(tripId: string) {
  const body = {
    jsonrpc: '2.0',
    id: 1,
    method: 'get_trip_summary',
    params: { tripId },
  };

  const res = await fetch(MCP_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${ACCESS_TOKEN}`,
    },
    body: JSON.stringify(body),
  });

  const { result } = await res.json();
  return result;
}

```

### Creating and Assigning Places

For write operations, the `create_and_assign_place` compound tool in [`src/mcp/tools/places.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/tools/places.ts) executes both `create_place` and `assign_place_to_day` within a single database transaction:

```typescript
const body = {
  jsonrpc: '2.0',
  id: 2,
  method: 'create_and_assign_place',
  params: {
    tripId: '12345',
    name: 'Kiyomizu-dera',
    lat: 34.9876,
    lng: 135.7950,
    dayId: 'day-3',
    assignment_notes: 'Morning visit, 9 am',
  },
};

await fetch(MCP_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${ACCESS_TOKEN}`,
  },
  body: JSON.stringify(body),
});

```

## Key Architectural Benefits of MCP in TREK

Implementing MCP provides three critical advantages for AI integration:

- **Single Source of Truth**: All read and write operations route through TREK's existing business logic in `src/mcp/tools/`, ensuring data integrity and validation rules remain consistent across web and AI interfaces.

- **Fine-Grained Permissions**: The scope system mapped in [`src/mcp/scopes.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/scopes.ts) allows administrators to restrict AI clients to specific domains—such as read-only trip viewing or full itinerary modification—without exposing the entire database.

- **Extensibility**: New capabilities can be added by registering additional tools in the `registerTools` function within [`src/mcp/index.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/index.ts); any MCP-compatible AI assistant immediately gains access without client-side updates.

## Summary

- **MCP in TREK** is a Model Context Protocol server implemented as an optional add-on in the `mauriceboe/TREK` repository.
- The server exposes **resources** (read-only data URIs) and **tools** (write operations) through the `/mcp` endpoint defined in [`src/mcp/index.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/index.ts).
- **OAuth 2.1** authentication with automatic discovery secures all connections, with scopes enforced by [`src/mcp/scopes.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/scopes.ts).
- **Claude Desktop** and **Cursor** connect via `npx mcp-remote`, which handles token management and JSON-RPC communication.
- AI assistants can invoke specific functions like `get_trip_summary` and `create_and_assign_place` to manipulate trip data programmatically while respecting user permissions.

## Frequently Asked Questions

### What does MCP stand for in TREK?

MCP stands for **Model Context Protocol**, an open protocol that standardizes how AI assistants interact with external data sources and tools. In TREK, it serves as the bridge between the application's trip-planning logic and LLM-based clients, converting internal business operations into a structured API that supports JSON-RPC communication over HTTP.

### How do I enable MCP in my TREK instance?

Administrators enable MCP through the **Admin Panel → Add-ons** interface. Once activated, the system automatically mounts the MCP server at `/mcp` and exposes the OAuth discovery endpoints. The add-on registration is handled in [`src/addons.ts`](https://github.com/mauriceboe/TREK/blob/main/src/addons.ts), while the server logic resides in [`src/mcp/index.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/index.ts).

### Which AI assistants support TREK's MCP integration?

Any AI client compatible with the Model Context Protocol can integrate with TREK. **Claude Desktop** and **Cursor** are the primary supported clients, both utilizing the `mcp-remote` helper to manage the OAuth flow and tool invocation. Other MCP-compliant assistants that support dynamic tool registration and OAuth 2.1 authentication can also connect using the same endpoint configuration.

### What permissions can I grant to AI assistants via MCP?

TREK's MCP implementation supports granular scopes defined in [`src/mcp/scopes.ts`](https://github.com/mauriceboe/TREK/blob/main/src/mcp/scopes.ts), including `trips:read` for viewing itineraries, `places:write` for creating and modifying locations, and `budget:write` for financial planning. During the OAuth consent flow, users select specific scopes to restrict the AI's capabilities, ensuring it can only access the data and operations explicitly authorized.