# Available OAuth Scopes for TREK MCP: Complete Permissions Guide

> Explore TREK MCP OAuth scopes. Understand 27 scopes across 13 groups, from read-only to destructive operations. Get the complete permissions guide for TREK MCP.

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

---

**TREK MCP defines 27 OAuth 2.0 scopes across 13 functional groups, ranging from read-only data access to destructive operations like permanent trip deletion, with write scopes automatically granting corresponding read permissions.**

The mauriceboe/TREK repository implements a Machine-Client-Portal (MCP) that relies on OAuth 2.0 scopes to enforce granular access control. Understanding the available TREK MCP OAuth scopes is essential for developers building AI clients that need to securely interact with trip data, packing lists, budgets, and collaborative features without requesting excessive permissions.

## Complete List of TREK MCP OAuth Scopes

According to the official [`wiki/MCP-Scopes.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/MCP-Scopes.md) file in the repository, TREK MCP organizes permissions into 13 functional groups. Each group typically exposes read and write scopes, with some including specialized delete or share permissions.

### Trips, Places, and Atlas

- **Trips**: `trips:read` (view trips, days, notes, members), `trips:write` (create, update, delete trips and manage members), `trips:delete` (permanent trip deletion), `trips:share` (manage public share links)
- **Places**: `places:read` (read places, assignments, tags), `places:write` (create, update, delete places and tags)
- **Atlas**: `atlas:read` (visited countries, regions, bucket-list), `atlas:write` (mark visited, manage bucket-list)

### Planning and Logistics

- **Packing**: `packing:read` (items, bags, categories), `packing:write` (add, update, delete, toggle, reorder items)
- **To-dos**: `todos:read` (trip to-do items), `todos:write` (create, update, toggle, delete, reorder)
- **Budget**: `budget:read` (budget items, expense breakdown), `budget:write` (create, update, delete budget items)
- **Reservations**: `reservations:read` (reservations and accommodation details), `reservations:write` (create, update, delete, reorder)

### Collaboration and Communication

- **Collaboration**: `collab:read` (notes, polls, messages), `collab:write` (create, update, delete collab content)
- **Notifications**: `notifications:read` (in-app notifications, unread counts), `notifications:write` (mark as read/unread individually or in bulk)

### Specialized Services

- **Vacation**: `vacay:read` (vacation planning data, entries, stats), `vacay:write` (create and manage vacation entries, holidays, team plans)
- **Geo**: `geo:read` (location search, map URL resolution, reverse-geocoding)
- **Weather**: `weather:read` (forecasts for trip locations and dates)
- **Journey**: `journey:read` (journeys, entries, contributors), `journey:write` (create, update, delete journeys and entries), `journey:share` (manage public share links without granting read access)

## Scope Rules and Permission Logic

The [`server/tests/unit/services/oauthService.test.ts`](https://github.com/mauriceboe/TREK/blob/main/server/tests/unit/services/oauthService.test.ts) file validates several critical scope behaviors that developers must understand when requesting TREK MCP OAuth scopes.

### Implicit Permissions

- **Write includes read**: Any `:write` scope automatically grants the matching `:read` permission. For example, `trips:write` implicitly includes `trips:read` capabilities.
- **Trips wildcard**: Any `trips:*` scope grants read access to trips, regardless of the specific variant.
- **Journey share exception**: Unlike other scopes, `journey:share` alone does **not** provide read access to journey data. It only enables link management, requiring explicit `journey:read` for content access.

### Utility Scopes and Bypass Mechanisms

- **Always available**: The utility scopes `list_trips` and `get_trip_summary` are universally accessible without explicit authorization.
- **Static tokens**: Static tokens and session JWTs bypass scope checks entirely, granting full access to all resources.
- **Add-on gating**: Access to Atlas, Collaboration, Vacation, and Journey features requires both the relevant scope and the corresponding add-on enabled by an admin, as enforced in the server implementation.

## Common Scope Presets for AI Clients

When registering OAuth clients in the admin panel, the Settings UI provides preset configurations for common use cases. These presets help developers request only the TREK MCP OAuth scopes their AI client truly needs.

- **Read-only AI assistant**: All `:read` scopes relevant to consumed data (e.g., `trips:read`, `budget:read`, `weather:read`).
- **Full trip planner**: All scopes except destructive `:delete` scopes, enabling comprehensive trip management without permanent deletion capabilities.
- **Budget review only**: `trips:read` plus `budget:read` for financial analysis without modification rights.
- **Packing-list assistant**: `trips:read`, `packing:read`, and `packing:write` for managing travel inventory.
- **Journey writer**: `trips:read`, `journey:read`, and `journey:write` for creating and managing travel narratives.

## Implementing OAuth Scopes in Code

The [`shared/src/oauth/oauth.schema.spec.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/oauth/oauth.schema.spec.ts) file defines the allowed scopes for client registration, while runtime enforcement occurs in the server OAuth service implementation.

### Requesting an Access Token

When exchanging an authorization code for a token, specify the required scopes in the request:

```bash
curl -X POST https://api.trek.example.com/oauth/token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d scope="trips:read packing:read packing:write"

```

### Node.js Implementation

Using axios to request tokens with specific TREK MCP OAuth scopes:

```javascript
const axios = require('axios');

async function getToken(code) {
  const response = await axios.post(
    'https://api.trek.example.com/oauth/token',
    new URLSearchParams({
      client_id: process.env.TREK_CLIENT_ID,
      client_secret: process.env.TREK_CLIENT_SECRET,
      grant_type: 'authorization_code',
      code,
      redirect_uri: process.env.TREK_REDIRECT_URI,
      scope: 'trips:read packing:read packing:write',
    })
  );
  return response.data.access_token;
}

```

### Calling Scoped Endpoints

Include the token in the Authorization header when accessing protected resources:

```bash
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.trek.example.com/v1/trips

```

If the token lacks `trips:read`, the server responds with **403 Forbidden**, as validated in [`oauthService.test.ts`](https://github.com/mauriceboe/TREK/blob/main/oauthService.test.ts).

## Key Source Files Reference

Understanding the TREK MCP OAuth scope implementation requires familiarity with these repository locations:

- **[`wiki/MCP-Scopes.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/MCP-Scopes.md)**: The authoritative source containing the complete table of all 27 scopes and their descriptions.
- **[`server/tests/unit/services/oauthService.test.ts`](https://github.com/mauriceboe/TREK/blob/main/server/tests/unit/services/oauthService.test.ts)**: Test suite validating scope string handling and permission enforcement.
- **[`shared/src/oauth/oauth.schema.spec.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/oauth/oauth.schema.spec.ts)**: Schema specification defining valid scope values for client registration.
- **[`MCP.md`](https://github.com/mauriceboe/TREK/blob/main/MCP.md)**: General MCP documentation linking to scope definitions and usage guidelines.

## Summary

- **TREK MCP OAuth scopes** comprise 27 permissions across 13 functional groups, including Trips, Places, Packing, Budget, and Journey.
- **Write scopes implicitly grant read access** to their respective resources, while `journey:share` uniquely does not include read permissions.
- **Add-on gated tools** require both the relevant scope and admin-enabled add-ons for Atlas, Collaboration, Vacation, and Journey features.
- **Utility scopes** `list_trips` and `get_trip_summary` are always available, while static tokens bypass all scope checks.
- **Scope validation** occurs in [`oauthService.test.ts`](https://github.com/mauriceboe/TREK/blob/main/oauthService.test.ts) and is defined in [`oauth.schema.spec.ts`](https://github.com/mauriceboe/TREK/blob/main/oauth.schema.spec.ts), with unauthorized requests returning 403 Forbidden.

## Frequently Asked Questions

### What happens if I request a scope that includes an add-on I don't have access to?

The server will reject the authorization request or fail at runtime when attempting to access add-on-gated tools like Atlas, Collaboration, Vacation, or Journey features. Both the specific scope and the corresponding add-on must be enabled by an admin, as documented in the MCP-Scopes wiki and enforced in the server implementation.

### Do I need to request both read and write scopes for the same resource?

No. When you request a write scope such as `trips:write` or `packing:write`, you automatically receive the corresponding read permission. The OAuth service handles this implicit grant, so requesting both is redundant but harmless.

### Why does my token return 403 Forbidden when accessing journeys?

If you are using `journey:share` without `journey:read`, you cannot access journey content. Unlike other TREK MCP OAuth scopes where write includes read, `journey:share` only permits managing public share links. You must explicitly include `journey:read` in your scope request to view journey data.

### What is the difference between static tokens and OAuth scopes?

Static tokens and session JWTs bypass all scope checks and grant full access to MCP resources, whereas OAuth tokens issued via the authorization flow must include specific TREK MCP OAuth scopes to access protected endpoints. The [`oauthService.test.ts`](https://github.com/mauriceboe/TREK/blob/main/oauthService.test.ts) file validates this distinction, with scoped tokens enforcing the 27-permission matrix defined in [`wiki/MCP-Scopes.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/MCP-Scopes.md).