Document MCP API token authentication by samgutentag · Pull Request #537 · trunk-io/docs

samgutentag · 2026-04-10T04:01:49Z

Documents API token authentication as an alternative to OAuth for the Trunk MCP server (shipped in v148, trunk-io/trunk2#3381).

Changes

Updated MCP server overview with both auth methods explained
Added API token config examples to all four client pages (Claude Code, Cursor, Gemini CLI, GitHub Copilot)

What's documented

OAuth remains default; API token for CI/headless environments or clients without OAuth support
Bearer token header configuration per client
Where to find the API token in the Trunk app

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

Documents API token auth as an alternative to OAuth for the Trunk MCP server. Useful for CI/headless environments and clients that don't support OAuth. Source: trunk-io/trunk2#3381 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Documents API token auth as an alternative to OAuth for the Trunk MCP server. Covers the README overview and all four client config pages (Claude Code, Cursor, GitHub Copilot, Gemini). Shipped in trunk2 v148 (#3381). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> https://claude.ai/code/session_01U4k4g3jSvW8Nu7LiCMtPNk

… examples Resolves merge conflict with remote branch. Improves README authorization section with OAuth spec link and org-level attribution note. Adds dedicated API token sections to all four client config pages (Claude Code, Cursor, GitHub Copilot, Gemini) with env var interpolation examples. Shipped in trunk2 v148 (#3381). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> https://claude.ai/code/session_01U4k4g3jSvW8Nu7LiCMtPNk

trunk-staging-io · 2026-04-10T04:01:53Z

Merging to main in this repository is managed by Trunk.

To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

claude · 2026-04-10T04:02:11Z

Claude finished @samgutentag's task in 2m 3s —— View job

PR Review

Gather context and read changed files
Review for typos, grammar, and formatting issues
Review for documentation best practices
Post final review

Summary

This PR is well-structured and accurately documents the API token authentication option across the overview page and all four client-specific pages. No blocking issues found.

What's good

Section headers are consistently renamed from ### Authentication → ### Authentication with OAuth (default) across all four client pages — clear and parallel structure.
VS Code's ${env:TRUNK_API_TOKEN} syntax is correctly distinguished from the ${TRUNK_API_TOKEN} used by other clients, with a helpful {% hint %} note explaining the difference.
Gemini CLI's "httpUrl" key is correctly used in its client-specific page (different from "url" used by others).
The PR also fixes a pre-existing copy/paste error in github-copilot-ide.md where the auth section incorrectly referred to "Cursor" instead of "GitHub Copilot".

Minor suggestions (non-blocking)

README.md generic JSON example — See inline comment. The overview's API token example uses "url", which works for most clients but not Gemini CLI (which needs "httpUrl"). A small note pointing readers to client-specific pages for the exact key would prevent confusion.

Pre-existing typos (not introduced by this PR, worth a follow-up):

cursor-ide.md:47: "follow insturctions" → "follow instructions"
github-copilot-ide.md:62: "follow insturctions" → "follow instructions"

Org-level caveat visibility — The README mentions "API token auth is org-level — all requests are attributed to the organization rather than to a specific user", but this isn't repeated on the per-client pages. Users who navigate directly to a client page won't see this important note. Consider adding a short callout or linking back to the overview.

Overall: no blocking issues. The documentation is accurate, consistent, and follows the existing patterns in the repo.

claude · 2026-04-10T04:04:07Z

+{
+  "mcpServers": {
+    "trunk": {
+      "url": "https://mcp.trunk.io/mcp",


Minor: this generic example uses "url" which is correct for Claude Code, Cursor, and GitHub Copilot — but Gemini CLI requires "httpUrl" instead. Consider adding a note that the exact config key varies by client, with a pointer to the client-specific pages.

github-actions

Auto-approved: Claude code review passed.

claude · 2026-05-05T18:33:13Z

Claude finished @samgutentag's task in 1m 2s —— View job

PR Review

Read CLAUDE.md for repo guidelines
Review changed files for typos, grammar, and formatting
Review for documentation best practices
Post final review

Summary

This PR is well-structured. The new API token sections are accurate, consistently formatted across all four client pages, and the client-specific differences (Gemini's "httpUrl", VS Code's ${env:...} syntax) are correctly handled. No blocking issues.

What's good

github-copilot-ide.md correctly fixes the pre-existing copy/paste bug that referred to "Cursor" instead of "GitHub Copilot" in the OAuth auth section.
Gemini CLI page correctly uses "httpUrl" in the API token JSON example (not "url"), matching the existing setup section.
The {% hint %} note in github-copilot-ide.md explaining the ${env:VARIABLE_NAME} vs ${VARIABLE_NAME} syntax difference is clear and helpful.
The org-level attribution caveat in README.md:52 is a useful heads-up for teams considering the API token path.

Minor suggestions (non-blocking)

README.md:43 — The overview's JSON example still uses "url", which works for most clients but not Gemini CLI (which requires "httpUrl"). This was flagged in the previous review and not yet addressed. A short note pointing readers to client-specific pages for the exact key would prevent confusion. Fix this →

cursor-ide.md:47 and github-copilot-ide.md:62 — Pre-existing "Login" (noun) should be "Log in" (verb) in both OAuth auth sections:

cursor-ide.md:47: "Login with your Trunk account" → "Log in with your Trunk account"
github-copilot-ide.md:62: "Login with your Trunk account" → "Log in with your Trunk account"

Consistency — The claude-code-cli.md API token intro mentions CI/headless environments explicitly ("If you are in a CI or headless environment, or prefer not to use the OAuth browser flow…"), while the other three client pages only say "If you prefer not to use the OAuth flow." Minor inconsistency, not wrong.

Overall: no blocking issues. Accurate, consistent, and well-structured.

github-actions

Auto-approved: Claude code review passed.

samgutentag · 2026-05-06T03:47:38Z

Triage status (2026-05-05): up to date with main. Review approved. Ready to merge.

samgutentag · 2026-05-06T20:58:49Z

Verification status (2026-05-06): live

Verified: customers can use this. Ready to publish.

Eng PR: trunk-io/trunk2#3381 (merged 2026-04-08)
Flag: none (no LaunchDarkly gate found in PR body or diff)
Signals:
- Merge commit on main (status: behind, merge intact)
- No feature flag patterns (useFeatureFlag, flags.ts, useFlag) in PR diff
- PR body explicitly says "shipped in v148"
- Auth method is a permanent additional code path (discriminated union on Authorization), not flag-gated

Branch is up to date with main. Suggested next action: ready to publish after content review.

claude · 2026-05-06T22:07:20Z

Claude finished @samgutentag's task in 1m 46s —— View job

PR Review

Read CLAUDE.md for repo guidelines
Review changed files for typos, grammar, and formatting
Review for documentation best practices
Post final review

Summary

Latest commit is a merge from main — no new content changes since the previous review. The PR remains accurate, consistent, and free of blocking issues. Confirming status: ready to merge.

What's good

All four client pages consistently rename ### Authentication → ### Authentication with OAuth (default) and add a parallel ### Alternative: Authentication with API token section.
Client-specific config keys are correctly differentiated: Gemini CLI uses "httpUrl" (gemini-cli.md:85), VS Code uses ${env:VARIABLE_NAME} (github-copilot-ide.md:87) with a clear {% hint %} callout explaining the difference (github-copilot-ide.md:94-96).
github-copilot-ide.md:50 correctly fixes the pre-existing copy/paste bug that referred to "Cursor" instead of "GitHub Copilot".
README.md:52 calls out org-level attribution — useful guidance for teams choosing between OAuth and API token.

Minor (non-blocking, carried over from prior reviews)

These were flagged in the 2026-04-10 and 2026-05-05 reviews and are still open. None of them block merge:

README.md:43 — Generic JSON example uses "url", but Gemini CLI requires "httpUrl". Consider a short note pointing readers to client-specific pages. Fix this →
Pre-existing "Login" → "Log in" in OAuth sections of two files (verb form):
- cursor-ide.md:47: "Login with your Trunk account and follow instructions" → "Log in with your Trunk account and follow the instructions"
- github-copilot-ide.md:62: "Login with your Trunk account and follow instructions" → "Log in with your Trunk account and follow the instructions"
- For reference, claude-code-cli.md:48 and gemini-cli.md:55 already use the corrected form.
Org-level caveat is README-only — The "API token auth is org-level" note (README.md:52) doesn't appear on any per-client page. Users navigating directly to a client page won't see it. A one-line callout or link back to the overview on each client page would help.
Intro phrasing inconsistency — claude-code-cli.md:62 mentions "CI or headless environment" explicitly, while the other three client pages just say "If you prefer not to use the OAuth flow." Not wrong, just slightly uneven.
cursor-ide.md:54-55 — Double blank line between the OAuth section and the new API token section. Other client pages use a single blank line.

Overall: no blocking issues. Approving the same as the prior two reviews — the documentation is accurate, well-structured, and matches the existing patterns in the repo.
• Branch

github-actions

Auto-approved: Claude code review passed.

samgutentag and others added 3 commits April 9, 2026 10:59

claude Bot reviewed Apr 10, 2026

View reviewed changes

github-actions Bot approved these changes Apr 10, 2026

View reviewed changes

Merge branch 'main' into sam-gutentag/mcp-api-token-auth

a204b28

github-actions Bot approved these changes May 5, 2026

View reviewed changes

Merge branch 'main' into sam-gutentag/mcp-api-token-auth

151450f

github-actions Bot approved these changes May 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document MCP API token authentication#537

Document MCP API token authentication#537
samgutentag wants to merge 5 commits intomainfrom
sam-gutentag/mcp-api-token-auth

samgutentag commented Apr 10, 2026

Uh oh!

trunk-staging-io Bot commented Apr 10, 2026

Uh oh!

claude Bot commented Apr 10, 2026 •

edited

Loading

Uh oh!

claude Bot Apr 10, 2026

Uh oh!

github-actions Bot left a comment

Uh oh!

claude Bot commented May 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment

Uh oh!

samgutentag commented May 6, 2026

Uh oh!

samgutentag commented May 6, 2026 •

edited

Loading

Uh oh!

claude Bot commented May 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Conversation

samgutentag commented Apr 10, 2026

Changes

What's documented

Uh oh!

trunk-staging-io Bot commented Apr 10, 2026

Uh oh!

claude Bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review

Summary

What's good

Minor suggestions (non-blocking)

Uh oh!

claude Bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

claude Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review

Summary

What's good

Minor suggestions (non-blocking)

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

samgutentag commented May 6, 2026

Uh oh!

samgutentag commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review

Summary

What's good

Minor (non-blocking, carried over from prior reviews)

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

claude Bot commented Apr 10, 2026 •

edited

Loading

claude Bot commented May 5, 2026 •

edited

Loading

samgutentag commented May 6, 2026 •

edited

Loading

claude Bot commented May 6, 2026 •

edited

Loading