mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-06-19 13:21:46 +00:00
v3.0.22 Bug Fixes & Improvements (#1041)
Bundles the v3.0.22 bug fixes and improvements. See the release notes for the full list.
This commit is contained in:
Julien G.
@@ -18,6 +18,16 @@ Once connected, an AI assistant can work with your TREK data in a single convers
|
||||
|
||||
Changes made through MCP are broadcast to all connected clients in real-time — exactly like changes made in the web UI.
|
||||
|
||||
## Authentication options
|
||||
|
||||
| Use case | Method |
|
||||
|---|---|
|
||||
| Interactive client (Claude.ai, Cursor, VS Code…) | OAuth 2.1 with browser consent — TREK issues tokens after you approve scopes in a consent screen |
|
||||
| AI agent or script running unattended | Machine client (client_credentials) — token obtained directly via `client_id` + `client_secret`, no browser ever opened |
|
||||
| Legacy setups | Static API token — deprecated, full access, no scopes |
|
||||
|
||||
See [MCP-Setup](MCP-Setup) for step-by-step instructions for each method.
|
||||
|
||||
## Requirements
|
||||
|
||||
- **MCP addon enabled** — an administrator must enable the MCP addon (`mcp`) from the Admin Panel before the `/mcp` endpoint becomes available and the MCP section appears in user settings.
|
||||
|
||||
+39
-26
@@ -1,6 +1,6 @@
|
||||
# MCP Setup
|
||||
|
||||
This page explains how to connect an AI assistant to your TREK instance. TREK supports two authentication methods: OAuth 2.1 (recommended) and static API tokens (deprecated).
|
||||
This page explains how to connect an AI assistant to your TREK instance. TREK supports three authentication methods: OAuth 2.1 with browser consent (recommended for interactive clients), machine clients with no browser login (recommended for AI agents and scripts), and static API tokens (deprecated).
|
||||
|
||||
<!-- TODO: screenshot: OAuth client registration form -->
|
||||
|
||||
@@ -23,25 +23,12 @@ Claude.ai (web) supports native MCP connections — no JSON config file required
|
||||
|
||||
### Claude Desktop
|
||||
|
||||
Claude Desktop connects via `mcp-remote`. After creating an OAuth client using the **Claude Desktop** preset (redirect URI: `http://localhost`), add the following to your Claude Desktop config:
|
||||
Claude Desktop supports native MCP connections — no JSON config file required:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"trek": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"mcp-remote",
|
||||
"https://<your-trek-instance>/mcp",
|
||||
"--static-oauth-client-info",
|
||||
"{\"client_id\": \"<your_client_id>\", \"client_secret\": \"<your_client_secret>\"}"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When the client starts it opens your browser to the TREK consent screen to complete the OAuth flow.
|
||||
1. In TREK, go to **Settings → Integrations → MCP → OAuth Clients** and click **Create**.
|
||||
2. Select the **Claude Desktop** preset. This fills in the redirect URI and a default scope set.
|
||||
3. Give the client a name, adjust scopes if needed, and save. Copy the client ID and client secret — the secret is shown only once.
|
||||
4. In Claude Desktop, open Settings → MCP and add a new server using your TREK URL (`https://<your-trek-instance>/mcp`). Claude Desktop will open your browser to complete the OAuth consent flow.
|
||||
|
||||
### Cursor, VS Code, Windsurf, and Zed
|
||||
|
||||
@@ -99,9 +86,34 @@ Create a client in TREK using the appropriate preset (Cursor, VS Code, Windsurf,
|
||||
|
||||
Each user can have up to **10 OAuth clients**.
|
||||
|
||||
## Option B: Static API token (deprecated)
|
||||
## Option B: Machine client — no browser login (for AI agents and scripts)
|
||||
|
||||
> **Deprecated:** Static tokens will stop working in a future version of TREK. Migrate to OAuth 2.1.
|
||||
Use this when your AI agent or automation script needs to authenticate silently without any browser interaction. Instead of going through an OAuth consent flow, the client exchanges a `client_id` and `client_secret` directly for an access token ([RFC 6749 §4.4 — Client Credentials grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)).
|
||||
|
||||
**Why this exists:** browser-based OAuth flows break when an AI agent runs unattended. The agent may fire multiple concurrent token refreshes, causing replay detection to invalidate the session and open browser windows. Machine clients sidestep this entirely — there is no refresh token and no rotation race.
|
||||
|
||||
**How it works:** the token acts as its owner (the user who created the client), scoped to the permissions chosen at creation. All TREK permission checks still apply — the AI agent can only access what you can access, narrowed further to the selected scopes.
|
||||
|
||||
### Create a machine client
|
||||
|
||||
1. Go to **Settings → Integrations → MCP → OAuth Clients** and click **New Client**.
|
||||
2. Tick **Machine client (no browser login)**. The redirect URI field disappears — machine clients don't need one.
|
||||
3. Give it a name, select scopes, and click **Register Client**.
|
||||
4. Copy the `client_id` and `client_secret` shown — the secret is displayed only once.
|
||||
|
||||
### How token management works
|
||||
|
||||
Your AI client uses the `client_id` and `client_secret` to request a token directly from TREK (`POST /oauth/token` with `grant_type=client_credentials`). Tokens are valid for 1 hour. When one expires, the client requests a new one silently — no browser window, no user action, no consent screen. This is handled entirely by the client.
|
||||
|
||||
### Who should use this
|
||||
|
||||
Machine clients are designed for **AI agent frameworks and custom MCP client implementations** that can call the token endpoint themselves and handle renewal programmatically. TREK advertises `client_credentials` in its OAuth discovery document (`/.well-known/oauth-authorization-server`), so any compliant client can discover and use it automatically.
|
||||
|
||||
> **`mcp-remote` users:** `mcp-remote` implements the browser-based `authorization_code` flow only — it does not support `client_credentials`. If you use `mcp-remote`, stick with Option A and use the preset for your client. The machine client option is not applicable.
|
||||
|
||||
## Option C: Static API token (deprecated)
|
||||
|
||||
> **Deprecated:** Static tokens will stop working in a future version of TREK. Migrate to OAuth 2.1 or machine clients.
|
||||
|
||||
Static tokens grant full access to all tools and resources with no scope restrictions. Sessions using a static token will receive deprecation warnings in the AI client on every tool call.
|
||||
|
||||
@@ -129,11 +141,12 @@ Each user can create up to **10 static tokens**.
|
||||
|
||||
## Authentication reference
|
||||
|
||||
| Method | Token prefix | Access level | Expiry |
|
||||
|---|---|---|---|
|
||||
| OAuth 2.1 access token | `trekoa_` | Scoped (per-consent) | 1 hour; auto-refreshed via 30-day rolling refresh token (`trekrf_`) |
|
||||
| OAuth client secret | `trekcs_` | Used during OAuth registration | No expiry (revoke via UI) |
|
||||
| Static API token | `trek_` | Full access | No expiry — **deprecated** |
|
||||
| Method | Grant | Token prefix | Access level | Expiry |
|
||||
|---|---|---|---|---|
|
||||
| OAuth 2.1 — browser consent | `authorization_code` | `trekoa_` | Scoped (per-consent) | 1 hour; auto-refreshed via 30-day rolling refresh token (`trekrf_`) |
|
||||
| Machine client — no browser | `client_credentials` | `trekoa_` | Scoped (per-client), acts as owner | 1 hour; re-request silently, no refresh token |
|
||||
| OAuth client secret | — | `trekcs_` | Used to authenticate the client at the token endpoint | No expiry (revoke via UI) |
|
||||
| Static API token | — | `trek_` | Full access | No expiry — **deprecated** |
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
Reference in New Issue
Block a user