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

> Master MCP OAuth 2.1 configuration for TREK. Follow our guide to set up authentication grants like authorization code and client credentials for seamless integration.

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

---

**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`](https://github.com/mauriceboe/TREK/blob/main/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:

```dotenv

# Required for OAuth 2.1 discovery and callbacks

APP_URL=https://trek.example.com

```

As documented in [`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md) and [`wiki/MCP-Setup.md`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/shared/src/oauth/oauth.schema.ts) and detailed in [`wiki/MCP-Overview.md`](https://github.com/mauriceboe/TREK/blob/main/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:

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

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

```bash
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:

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

```

Include this token in subsequent MCP API requests:

```bash
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`](https://github.com/mauriceboe/TREK/blob/main/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:

```bash
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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/wiki/Admin-MCP-Tokens.md).