Skip to content

feat(mcp): bearer token support when adding remote MCP servers - #1398

Merged
kentcdodds merged 2 commits into
mainfrom
cursor/mcp-server-bearer-token-002f
Aug 12, 2026
Merged

kentcdodds merged 2 commits into
mainfrom
cursor/mcp-server-bearer-token-002f

Conversation

@kentcdodds

@kentcdodds kentcdodds commented Aug 12, 2026 •

Copy link
Copy Markdown
Member

Summary

Addresses CAM's platform feedback: /account/mcp-servers only accepted name + URL, so bearer-token MCP servers could not be connected.

Adds an optional bearer token on:

  • /account/mcp-servers add form (password field)
  • Account MCP servers API (bearerToken)
  • mcp_server_add capability

Normalization accepts bare tokens (Bearer <token>), scheme-prefixed values, and full Authorization: … header pastes. The credential is stored only in the per-user MCP client hub's Agents SDK server_options (never in D1 or list/detail responses).

Test plan

  • Unit: bearer token normalization (including Authorization: header pastes)
  • Unit: settings service forwards Authorization headers to hub; D1 row has no token
  • Unit: account API add action passes bearerToken
  • CI validate green (prior commit); waiting on follow-up for paste-fix
  • After merge: mark platform feedback resolved
System recap — extends existing primitives (medium risk)

Mode: recap · Base: main @ c7cd824 · Head: follow-up after Bugbot paste-fix

Classification: extends — MCP client add contract and account UI now accept optional static Authorization credentials.

Primitives touched

Primitive Group Impact
mcp-client-servers assistant extends — optional bearerToken → durable Authorization header on hub transport
app-ui surfaces extends — add-server form gains optional bearer token field

System map

Add-server flows (UI / API / capability) now pass an optional bearer credential into the per-user MCP client hub as a durable Authorization header.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	appUi["app-ui<br/>Browser app (Remix 3)"]:::extended
	mcpClientServers["mcp-client-servers<br/>MCP client servers"]:::extended
	appUi -->|"POST bearerToken on /account/mcp-servers.json"| mcpClientServers
	mcpClientServers -->|"transport.headers Authorization on registerServer"| mcpClientServers
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff
Loading

Before / after

Surface Before After
Add form name + URL name + URL + optional bearer token
mcp_server_add { name, url } { name, url, bearerToken? }
Hub addServer OAuth provider only optional headers.Authorization persisted in DO server_options

Invariants

Per-user isolation unchanged: credentials stay in the user-scoped MCP client hub DO and are never returned by list/detail APIs.

Open in Web Open in Cursor 

Summary by CodeRabbit

  • New Features

    • Added optional bearer-token authentication for MCP server connections.
    • MCP server setup now accepts tokens through the management interface and server-add capability.
    • Tokens are normalized into Authorization headers and excluded from saved settings and snapshots.
    • OAuth remains available when static bearer-token authentication is not used.
  • Documentation

    • Updated setup and architecture guidance for bearer tokens, HTTPS, storage, and authentication behavior.
  • Bug Fixes

    • Improved handling of empty, prefixed, formatted, and oversized authorization values.

CAM's platform feedback: /account/mcp-servers only offered name and URL,
so bearer-token MCP servers could not be connected. Add an optional bearer
token on the UI, account API, and mcp_server_add capability, and pass it as
a durable Authorization header through the per-user MCP client hub.

Co-authored-by: Kent C. Dodds <me+github@kentcdodds.com>
@coderabbitai

coderabbitai Bot commented Aug 12, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: afa3ea15-8671-4772-8049-2151dd2e306c

📥 Commits

Reviewing files that changed from the base of the PR and between b41eb43 and 4cef6c5.

📒 Files selected for processing (4)
  • docs/use/mcp-client-servers.md
  • packages/shared/src/mcp-servers.node.test.ts
  • packages/shared/src/mcp-servers.ts
  • packages/worker/client/routes/account-mcp-servers.tsx
🚧 Files skipped from review as they are similar to previous changes (4)
  • packages/worker/client/routes/account-mcp-servers.tsx
  • docs/use/mcp-client-servers.md
  • packages/shared/src/mcp-servers.node.test.ts
  • packages/shared/src/mcp-servers.ts

📝 Walkthrough

Walkthrough

MCP server setup now accepts optional bearer tokens. Shared utilities normalize credentials and create Authorization headers. The hub applies headers during connection while excluding tokens from persisted D1 settings and snapshots. The UI, capability, tests, and documentation expose the new flow.

Changes

MCP bearer-token authentication

Layer / File(s) Summary
Credential normalization and headers
packages/shared/src/mcp-servers.ts, packages/shared/src/mcp-servers.node.test.ts
Bearer tokens support blank values, existing authorization schemes, automatic Bearer formatting, pasted Authorization: prefixes, and an 8,192-character limit. Tests cover normalization and header generation.
MCP server setup inputs
packages/worker/client/routes/account-mcp-servers.tsx, packages/worker/src/app/handlers/account-mcp-servers.ts, packages/worker/src/mcp/capabilities/mcp-servers/mcp-server-add.ts, packages/worker/src/app/handlers/account-mcp-servers.node.test.ts
The management form and mcp_server_add capability accept optional bearer tokens. The handler trims and forwards submitted credentials.
Hub registration and transport headers
packages/worker/src/mcp-client/settings-service.ts, packages/worker/src/mcp-client/hub-client.ts, packages/worker/src/mcp-client/hub.ts, packages/worker/src/mcp-client/settings-service.node.test.ts
addMcpServer normalizes credentials and passes Authorization headers to the hub. The hub applies headers to MCP transport configuration without persisting tokens in D1 settings or snapshots.
Authentication documentation
docs/use/mcp-client-servers.md, docs/contributing/architecture/mcp-client-servers.md
Documentation describes static bearer-token setup, private credential handling, and OAuth behavior when static authorization is sufficient.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ManagementUI
  participant AccountMcpServerHandler
  participant SettingsService
  participant McpClientHub
  participant MCPServer
  ManagementUI->>AccountMcpServerHandler: Submit bearerToken
  AccountMcpServerHandler->>SettingsService: Call addMcpServer
  SettingsService->>SettingsService: Normalize token and derive Authorization header
  SettingsService->>McpClientHub: Register server with headers
  McpClientHub->>MCPServer: Connect with Authorization header
Loading

Possibly related PRs

  • kentcdodds/kody#1324: Both changes modify MCP server setup and authentication flows, but this PR adds static bearer-token support while that PR addresses OAuth origin and redirect guidance.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly and concisely identifies the main change: bearer token support for adding remote MCP servers.
Description check ✅ Passed The description explains the intent, summarizes the changes, documents testing, and includes system-impact details, although it uses Summary instead of the required Intent heading.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch cursor/mcp-server-bearer-token-002f

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@kentcdodds
kentcdodds marked this pull request as ready for review August 12, 2026 02:28
@github-actions

github-actions Bot commented Aug 12, 2026 •

Copy link
Copy Markdown
Contributor

🔎 Preview deployed: https://kody-pr-1398.kody-a99.workers.dev

Worker: kody-pr-1398
Runtime worker: kody-pr-1398-runtime (https://kody-pr-1398-runtime.kody-a99.workers.dev)
D1: kody-pr-1398-db
KV: kody-pr-1398-oauth-kv

Mocks:

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit b41eb43. Configure here.

Comment thread packages/shared/src/mcp-servers.ts Resolved
@kentcdodds

Copy link
Copy Markdown
Member Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Aug 12, 2026 •

Copy link
Copy Markdown
⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Bugbot correctly flagged that pasting "Authorization: Bearer …" would be
double-wrapped. Strip the header name before scheme/token normalization.

Co-authored-by: Kent C. Dodds <me+github@kentcdodds.com>
@kentcdodds
kentcdodds merged commit 7ec8929 into main Aug 12, 2026
10 checks passed
@kentcdodds
kentcdodds deleted the cursor/mcp-server-bearer-token-002f branch August 12, 2026 02:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants