How to Set Up and Use the Built-in MCP Server for AI Integration in TREK

TREK's built-in Model Context Protocol (MCP) server enables AI assistants to securely read and modify travel data through a granular, OAuth 2.1-protected API once an admin enables the addon and configures the public URL.

The TREK repository (mauriceboe/TREK) ships with a native MCP implementation that exposes your trips, packing lists, and budgets as structured resources to compatible AI clients. This guide walks through the complete setup—from enabling the service in the admin panel to issuing your first authenticated tool call.

Prerequisites for Enabling the MCP Server

Before any AI client can connect, you must activate the MCP addon and ensure your instance advertises the correct public endpoint.

Enable the MCP Addon in Admin Panel

An administrator must toggle the MCP service on via Admin Panel → Addons. Until this step is complete, the /mcp endpoint returns 404 Not Found, and the MCP configuration section remains hidden from user settings. According to the source documentation in MCP.md, this gate prevents accidental exposure of travel data before OAuth flows are properly configured.

Configure the APP_URL Environment Variable

The environment variable APP_URL must contain the public base URL of your TREK instance (e.g., https://trek.example.com). This value drives the discovery documents hosted at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, which MCP clients query automatically to locate token endpoints. Without this setting, dynamic client registration and token refresh will fail.

Connecting Your AI Client via OAuth 2.1

TREK implements the modern OAuth 2.1 flow with Dynamic Client Registration (RFC 7591), eliminating the need to manually create API keys in most cases.

Client Configuration Examples

For Claude Desktop, Cursor, or any client supporting mcp-remote, add the following to your MCP configuration file (e.g., ~/.config/mcp.json):

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

Replace https://your-trek-instance.com/mcp with your actual public URL. When the client launches, it automatically opens a browser to complete the OAuth consent flow and stores the short-lived token internally.

For legacy clients that require static tokens (deprecated), use:

{
  "mcpServers": {
    "trek": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-trek-instance.com/mcp",
        "--header",
        "Authorization: Bearer trek_your_token_here"
      ]
    }
  }
}

Note that static tokens with the trek_ prefix are scheduled for removal; migrate to OAuth tokens (trekoa_ prefix) for production use.

Understanding the Discovery Flow

When the MCP client starts, it performs the following steps automatically:

1. Queries /.well-known/oauth-protected-resource to identify the authorization server
2. Registers itself dynamically via the RFC 7591 endpoint
3. Opens the browser for user authentication and consent
4. Receives a short-lived access token and refresh token pair

This process requires no manual copying of tokens into configuration files, reducing the risk of credential leakage.

Granting Scopes and Permissions

During the consent screen, users select which granular scopes the AI may access. Scope selection determines which tools and resources are exposed for that session.

Available Scopes

Key scopes include:

• trips:write – Grants permission to create and modify trips (implicitly includes trips:read)
• packing:write – Allows AI to manage packing lists (implicitly includes packing:read)
• budget:read – Provides read access to budget data
• places:write – Enables adding and editing destinations

Scope Enforcement

The scope validation logic in server/src/mcp/scopes.ts filters the available tool set at runtime. If a user grants only trips:read, the AI receives the resource trek://trips but cannot invoke the create_trip or update_trip tools. This enforcement happens in server/src/mcp/sessionManager.ts, which maintains per-user, per-client session state and rate limits.

Core MCP Components

The TREK MCP server, mounted on /mcp in server/src/mcp/index.ts, exposes three primary interaction patterns: resources, tools, and prompts.

Resources (Read-Only Data)

Resources provide structured data via trek:// URIs. For example, trek://trips returns a JSON list of all trips, while trek://packing/{tripId} returns the packing list for a specific trip. These are read-only channels that help the AI understand current state before proposing modifications. The resource handlers are registered in server/src/mcp/resources.ts.

Tools (Read-Write Actions)

Tools mutate data and are implemented in server/src/mcp/tools/*.ts. Common tools include:

• create_trip – Creates a new trip with specified dates and metadata
• add_place – Adds a destination to an existing trip
• update_budget – Adjusts budget allocations

Only tools matching the granted scopes appear in the session's tool list, as enforced by the scope mapper in server/src/mcp/scopes.ts.

Predefined Prompts

TREK includes system prompts such as trip-summary and packing-list that generate high-level summaries without requiring multiple tool calls. These prompts are defined in MCP.md and can be invoked directly by the AI client to produce formatted itineraries or checklist recommendations.

Making Your First MCP Request

Once authenticated, interact with the server using standard MCP JSON-RPC messages. For example, to list trips:

{
  "resource": "trek://trips",
  "method": "GET"
}

To create a trip via tool invocation:

{
  "tool": "create_trip",
  "params": {
    "name": "Iceland Adventure",
    "startDate": "2024-09-01",
    "endDate": "2024-09-10"
  }
}

For Node.js applications using mcp-remote programmatically:

const { spawn } = require('child_process');

const proc = spawn('npx', ['mcp-remote', 'https://your-trek-instance.com/mcp']);
proc.stdout.pipe(process.stdout);
proc.stderr.pipe(process.stderr);

Integration tests in server/tests/integration/mcp.test.ts verify that the /mcp endpoint correctly handles POST, GET, and DELETE methods for resource and tool operations.

Security and Token Management

The server/src/mcp/sessionManager.ts file handles session revocation, rate limiting, and cleanup. If an admin disables the MCP addon in the Admin Panel, all active sessions are immediately invalidated. Users can also revoke specific client access from their Settings page.

Static API tokens (trek_ prefix) remain supported for backward compatibility but will be removed in future releases. OAuth 2.1 tokens (trekoa_ prefix) expire quickly and refresh automatically, minimizing the window of exposure if a token is intercepted.

Summary

• Enable the addon first – The /mcp endpoint returns 404 until toggled in Admin Panel → Addons.
• Set APP_URL – Required for OAuth discovery documents and dynamic client registration.
• Use OAuth 2.1 – Modern clients auto-register and handle tokens; static trek_ tokens are deprecated.
• Grant minimal scopes – Only selected scopes (e.g., trips:write, packing:read) expose corresponding tools.
• Session enforcement – server/src/mcp/sessionManager.ts manages rate limits and revocation in real-time.

Frequently Asked Questions

What is the Model Context Protocol (MCP) in TREK?

The Model Context Protocol is an open standard that allows AI assistants to securely interact with external data sources. In TREK, the MCP server exposes travel data as resources and actions as tools, protected by OAuth 2.1, enabling AI clients to read trip itineraries and modify packing lists with user consent.

Why is the APP_URL environment variable required?

APP_URL must point to your public TREK instance so that MCP clients can locate the OAuth discovery documents at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Without this variable, dynamic client registration and token refresh flows will fail, preventing any AI connection.

How do I revoke an AI session if I no longer trust the client?

Navigate to your TREK Settings page and locate the MCP section to revoke individual client tokens. Administrators can disable the MCP addon entirely in the Admin Panel, which immediately terminates all active sessions via the cleanup logic in server/src/mcp/sessionManager.ts, or use the admin panel in admin/src/mcpTokens.ts to view and revoke specific tokens.

Can I use static API tokens instead of OAuth 2.1?

While static tokens with the trek_ prefix are currently supported for legacy clients, they are deprecated and will be removed. OAuth 2.1 tokens (trekoa_ prefix) are the recommended approach, offering automatic refresh and better security through short-lived credentials.

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