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

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, the server initializes through an McpServer instance that aggregates registrations from src/mcp/resources.ts and the src/mcp/tools/ directory:

// 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.

2. Scope Enforcement: The system defines specific capabilities such as trips:read, places:write, and budget:write in 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 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:

{
  "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:

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 executes both create_place and assign_place_to_day within a single database transaction:

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 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; 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.
• OAuth 2.1 authentication with automatic discovery secures all connections, with scopes enforced by 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, while the server logic resides in 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, 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.

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