Document MCP API token authentication

flaky-tests/use-mcp-server/README.md

@@ -24,7 +24,32 @@ Our MCP server is available at `https://mcp.trunk.io/mcp` and exposes the follow
 
 ### Authorization
 
-The Trunk MCP server supports the OAuth 2.0 + OpenID Connect standard for MCP authorization.
+The Trunk MCP server supports two authentication methods.
+
+**OAuth (default)**
+
+OAuth 2.0 + OpenID Connect is the default. MCP clients that support the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) will initiate the OAuth flow automatically. Most interactive clients (Cursor, Claude Code, GitHub Copilot) use this path.
+
+**API token**
+
+As an alternative, you can authenticate with your Trunk organization API token. This is useful for MCP clients that do not support OAuth, CI/headless environments, or quick manual setup.
+
+Find your token under **Settings > API** in the Trunk dashboard. Pass it as a Bearer token in the `Authorization` header:
+
+```json
+{
+  "mcpServers": {
+    "trunk": {
+      "url": "https://mcp.trunk.io/mcp",
+      "headers": {
+        "Authorization": "Bearer <your-trunk-api-token>"
+      }
+    }
+  }
+}
+```
+
+API token auth is org-level — all requests are attributed to the organization rather than to a specific user. OAuth remains the preferred method for interactive use because it provides user-level identity.
 
 ### Get started
 

flaky-tests/use-mcp-server/configuration/claude-code-cli.md

@@ -29,7 +29,7 @@ Add the following [configuration](https://docs.anthropic.com/en/docs/claude-code
 }
 ```
 
-### Authentication
+### Authentication with OAuth (default)
 
 After the MCP server was added to Claude Code, users need to authorize to communicate with the server. Follow these steps to complete auth.
 
@@ -41,7 +41,7 @@ In your terminal, run `claude` .
 
 Claude Code should recognize that auth is required. Run `/mcp` to authenticate, select trunk, and hit Enter:
 
-<figure><img src="../../../../.gitbook/assets/Screenshot 2025-09-10 at 12.02.48 PM.png" alt="" width="370"><figcaption></figcaption></figure>
+<figure><img src="../../../../.gitbook/assets/Screenshot 2025-09-10 at 12.02.48 PM.png" alt="" width="370"><figcaption></figcaption></figure>
 
 **Step 3: Login & authorize**
 
@@ -56,3 +56,25 @@ Authentication successful. Connected to trunk.
 ```
 
 **With auth completed, Claude Code will be able to fetch the tools exposed by Trunk's MCP server.**
+
+### Alternative: Authentication with API token
+
+If you are in a CI or headless environment, or prefer not to use the OAuth browser flow, you can authenticate with your Trunk organization API token instead.
+
+Find your token under **Settings > API** in the Trunk dashboard, then add it to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "trunk": {
+      "url": "https://mcp.trunk.io/mcp",
+      "type": "http",
+      "headers": {
+        "Authorization": "Bearer ${TRUNK_API_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Set the `TRUNK_API_TOKEN` environment variable to your org API token. Claude Code interpolates environment variables in MCP configuration files automatically.

flaky-tests/use-mcp-server/configuration/cursor-ide.md

@@ -28,7 +28,7 @@ Add the following [configuration](https://docs.cursor.com/en/context/mcp#model-c
 }
 ```
 
-### Authentication
+### Authentication with OAuth (default)
 
 After the MCP server was added to Cursor, users need to authorize Cursor to communicate with the server. Follow these steps to complete auth.
 
@@ -51,3 +51,25 @@ A new webpage will be opened. Login with your Trunk account and follow insturcti
 Follow instructions to get back to Cursor. With auth completed, Cursor will be able to fetch the tools exposed by Trunk's MCP server:
 
 <figure><img src="../../../../.gitbook/assets/Screenshot 2025-09-10 at 11.29.00 AM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+
+### Alternative: Authentication with API token
+
+If you prefer not to use the OAuth flow, you can authenticate with your Trunk organization API token. Find your token under **Settings > API** in the Trunk dashboard.
+
+Add the token to your `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "trunk": {
+      "url": "https://mcp.trunk.io/mcp",
+      "headers": {
+        "Authorization": "Bearer ${TRUNK_API_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Set `TRUNK_API_TOKEN` as an environment variable. Cursor interpolates environment variables in MCP configuration files automatically.

flaky-tests/use-mcp-server/configuration/gemini-cli.md

@@ -32,7 +32,7 @@ Add the following [configuration](https://github.com/google-gemini/gemini-cli/bl
 
 
 
-### Authentication
+### Authentication with OAuth (default)
 
 After the MCP server was added to Gemini, users need to authorize to communicate with the server. Follow these steps to complete auth.
 
@@ -71,3 +71,24 @@ Follow instructions to get back to Gemini. A confirmation should be shown:
 ```
 
 **With auth completed, Gemini will be able to fetch the tools exposed by Trunk's MCP server.**
+
+### Alternative: Authentication with API token
+
+If you prefer not to use the OAuth flow, you can authenticate with your Trunk organization API token. Find your token under **Settings > API** in the Trunk dashboard.
+
+Add the token to your `.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "trunk": {
+      "httpUrl": "https://mcp.trunk.io/mcp",
+      "headers": {
+        "Authorization": "Bearer ${TRUNK_API_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Set `TRUNK_API_TOKEN` as an environment variable. Gemini CLI interpolates environment variables in MCP configuration files automatically.

flaky-tests/use-mcp-server/configuration/github-copilot-ide.md

@@ -45,9 +45,9 @@ Add the following [configuration](https://code.visualstudio.com/docs/copilot/cha
 }
 ```
 
-### Authentication
+### Authentication with OAuth (default)
 
-After the MCP server was added to Cursor, users need to authorize Cursor to communicate with the server. Follow these steps to complete auth.
+After the MCP server was added, users need to authorize GitHub Copilot to communicate with the server. Follow these steps to complete auth.
 
 
 
@@ -71,3 +71,27 @@ Follow instructions to get back to GitHub Copilot. With auth completed, GitHub C
 2025-09-10 12:49:16.975 [info] Discovered 2 tools
 ```
 
+### Alternative: Authentication with API token
+
+If you prefer not to use the OAuth flow, you can authenticate with your Trunk organization API token. Find your token under **Settings > API** in the Trunk dashboard.
+
+Add the token to your `.vscode/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "trunk": {
+      "url": "https://mcp.trunk.io/mcp",
+      "type": "http",
+      "headers": {
+        "Authorization": "Bearer ${env:TRUNK_API_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+{% hint style="info" %}
+VS Code uses `${env:VARIABLE_NAME}` syntax for environment variable interpolation in MCP configuration files, unlike other clients which use `${VARIABLE_NAME}`.
+{% endhint %}
+