How to Configure MCP OAuth 2.1 for TREK: Complete Setup Guide

TLDR: Set the APP_URL environment variable to your public domain, enable the MCP add-on in the TREK admin panel, then create an OAuth 2.1 client in Settings → Integrations → MCP using either the authorization_code grant for interactive applications or client_credentials for machine-to-machine authentication.

TREK (mauriceboe/TREK) implements the Model Context Protocol (MCP) using OAuth 2.1 as its primary authentication mechanism. To connect external AI clients like Claude or Cursor to your TREK instance, you must configure the OAuth flow correctly, expose a public URL via environment variables, and manage client credentials securely according to the schema defined in shared/src/oauth/oauth.schema.ts.

Enable MCP and Configure the Public URL

Before creating clients, you must enable the MCP add-on and expose your instance to the internet.

The MCP add-on is disabled by default. Navigate to Admin → Add-ons and toggle the Model Context Protocol extension to active. Once enabled, TREK requires the APP_URL environment variable to generate the OAuth discovery document at /.well-known/oauth-authorization-server and to construct valid redirect URIs.

Without APP_URL, TREK falls back to localhost URLs that external clients cannot reach, breaking the authentication flow. Set this in your .env file or container orchestration configuration:

# Required for OAuth 2.1 discovery and callbacks

APP_URL=https://trek.example.com

As documented in wiki/Environment-Variables.md and wiki/MCP-Setup.md, this variable is mandatory for OIDC/OAuth compliance and enables the discovery endpoint that MCP clients use to locate authorization and token endpoints.

Create OAuth Clients in the TREK UI

Once the add-on is active, create OAuth 2.1 credentials through the TREK web interface.

Navigate to Settings → Integrations → MCP → OAuth Clients. Click Create to generate a new client. The interface, implemented in the frontend code referenced in wiki/MCP-Setup.md, allows you to configure:

• Client name: A descriptive label for identification.
• Grant type: Select authorization_code for interactive browser flows or client_credentials for headless machine access.
• Scopes: Choose from preset configurations like Claude AI (full access) or VS Code (read-only), or manually select from 27 granular permissions listed in wiki/MCP-Scopes.md.

TREK permits up to 10 OAuth clients per user. After creation, securely store the generated client_id and client_secret; the secret is shown only once during initialization.

Implement OAuth 2.1 Grant Flows

TREK supports two OAuth 2.1 grant types as defined in shared/src/oauth/oauth.schema.ts and detailed in wiki/MCP-Overview.md. Choose the flow that matches your client architecture.

Authorization Code Flow for Interactive Clients

Use the authorization_code grant for applications that can open a browser window to request user consent, such as Claude Desktop or VS Code extensions.

The flow begins with a redirect to the authorization endpoint:

// Redirect user to TREK consent screen
window.location = `${APP_URL}/oauth/authorize?response_type=code&client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=read:trips`;

After the user authenticates, TREK redirects to your specified redirect_uri with a temporary code. Exchange this code for tokens:

// Exchange code for access token
fetch(`${APP_URL}/oauth/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    code: AUTH_CODE,
    redirect_uri: REDIRECT_URI
  })
})
  .then(r => r.json())
  .then(data => {
    // data.access_token starts with "trekoa_"
    // data.refresh_token starts with "trekrf_"
  });

Client Credentials Flow for Machine-to-Machine Access

For AI agents, scripts, or backend services that cannot open a browser, use the client_credentials grant. This flow authenticates directly without user interaction.

Request a token via HTTP Basic authentication:

curl -X POST https://trek.example.com/oauth/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials&scope=read:trips write:notes"

The JSON response contains an access token ready for immediate use:

{
  "access_token": "trekoa_XXXXXXXXXXXXXXXX",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:trips write:notes"
}

Include this token in subsequent MCP API requests:

curl -H "Authorization: Bearer trekoa_XXXXXXXXXXXXXXXX" \
  https://trek.example.com/mcp/trips

Token Lifecycle and Security Specifications

TREK OAuth tokens follow strict conventions to ensure security and traceability.

Access tokens carry the prefix trekoa_ and expire after approximately one hour (3600 seconds). Refresh tokens use the prefix trekrf_ and rotate automatically upon each use, providing seamless session continuity without storing long-lived credentials. As noted in wiki/MCP-Overview.md, clients should implement automatic refresh logic to handle the short token lifespan.

To manually revoke a token before expiry, call the revocation endpoint:

curl -X POST https://trek.example.com/oauth/revoke \
  -u "<client_id>:<client_secret>" \
  -d "token=trekoa_XXXXXXXXXXXXXXXX"

Revoke Sessions and Manage Access

Administrators can centrally manage OAuth sessions from the Admin → MCP Access panel, documented in wiki/Admin-MCP-Tokens.md. This interface allows you to:

• View active sessions by client.
• Revoke individual tokens immediately.
• Delete entire OAuth clients to cut off all associated access.

Revocation is instant; clients holding deleted credentials will receive 401 Unauthorized responses on their next request.

Summary

Configuring MCP OAuth 2.1 for TREK requires coordination between environment variables, UI configuration, and client implementation:

• Set APP_URL in your environment to enable public OAuth discovery and callback URLs.
• Enable the MCP add-on in Admin → Add-ons before creating clients.
• Choose authorization_code for interactive clients that can open browsers, or client_credentials for machine-to-machine authentication.
• Store tokens securely: Access tokens use the trekoa_ prefix and expire in one hour; refresh tokens use trekrf_ and rotate automatically.
• Manage access through the Admin → MCP Access panel or the revocation API endpoint.

Frequently Asked Questions

What happens if I don't set the APP_URL environment variable?

Without APP_URL, TREK generates OAuth discovery documents and redirect URIs using localhost addresses. External MCP clients like Claude AI or Cursor cannot reach these internal addresses, causing authentication failures. The APP_URL must point to your publicly accessible domain as configured in wiki/Environment-Variables.md.

Can I use the same OAuth client for both Claude AI and automated scripts?

No. You should create separate OAuth clients for different use cases. Interactive applications require the authorization_code grant with browser-based consent, while automated scripts need the client_credentials grant. TREK allows up to 10 clients per user, enabling you to scope permissions appropriately for each integration type.

How do I refresh an expired access token?

TREK issues rotating refresh tokens with the trekrf_ prefix. When your access token (starting with trekoa_) expires after approximately one hour, submit the refresh token to the /oauth/token endpoint with grant_type=refresh_token. TREK will return a new access token and a new refresh token, invalidating the old one for security.

Where can I revoke access if a client is compromised?

Navigate to Admin → MCP Access in the TREK web interface to view all active sessions and revoke specific tokens immediately. Alternatively, delete the entire OAuth client from Settings → Integrations → MCP → OAuth Clients to invalidate all associated tokens instantly, as documented in wiki/Admin-MCP-Tokens.md.

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