HTTP MCP Server OAuth authentication (Visual Studio Code MCP Support) by mdthorpe-sc · Pull Request #154 · useshortcut/mcp-server-shortcut

mdthorpe-sc · 2026-02-19T20:38:37Z

OAuth proxy foundation (HTTP server)
- Added full OAuth provider implementation in src/auth/provider.ts.
- Integrated MCP SDK OAuth routes + bearer middleware in src/server-http.ts.
- Added callback relay flow (/oauth/callback) and upstream token exchange/refresh handling.
- Added token caching + refresh behavior for issued OAuth tokens.
Security hardening
- Client secret exposure fix: registration/client lookup now return public client metadata (secret not exposed to MCP clients), while upstream secret remains server-side.
- Session ownership binding fix: reintroduced session-bound token checks in src/server-http.ts (including helper methods and enforcement on session reuse paths).
Auth testing coverage
- Added large mocked auth test suite: src/auth/oauth.test.ts.
- Added staging integration auth tests: src/auth/oauth-integration.test.ts.
Operational config behavior
- Redirect URI allowlisting now depends on OAUTH_ALLOWED_REDIRECT_URIS (comma-delimited env var) in provider startup path.
- MCP_SERVER_URL is used to derive OAuth issuer/base/resource metadata identity (important for env isolation and VS Code cache behavior).
CI/CD and deploy pipeline changes
- Updated .github/workflows/pipeline.yml to split/build dependencies (build-docker + build-scripts) and update deploy job wiring.
- Updated build workflow (build_ecr_image.yml) and CodeDeploy startup behavior (including env file mount in start script).
Supporting app/library updates
- src/client/shortcut.ts updates (token/client handling support for refreshed sessions).
- Various test and tool file touch-ups.
- README.md and docs/oauth-proxy-implementation.md updates.
- package.json/package-lock.json churn from dependency/script updates.

Summary by CodeRabbit

New Features
- OAuth 2.0 (PKCE) login and Bearer token authentication for MCP endpoints with token caching and auto-refresh.
- Hosted-server-first configuration and OAuth callback support for connected clients.
Documentation
- Major README rewrite: streamlined hosted setup, unified tool tables, new local-server and developer guides, and simplified support section.
Chores
- CI/CD workflow and deployment updates; improved HTTP debug logging.
Tests
- New unit and integration tests covering OAuth flows.

Consolidates this branch's work to tighten token/session security, add OAuth provider and integration test coverage, and improve HTTP diagnostics and deployment workflows for local and remote MCP usage. Also updates docs, tooling, and dependency versions needed to support the new auth and release behavior.

… (http)

mdthorpe-sc · 2026-02-20T17:29:38Z

Hey @andreasmcdermott Thanks for getting in there and checking stuff, I have a bad habit of creating PRs without Draft mode.. I've finished merging the old/new docs and tablifying (I think?)

I also pulled out the developer stuff into its own doc. I think it makes more sense.

andreasmcdermott

One section was not copied from the README to the new markdown file. Other than that looks good!

andreasmcdermott · 2026-03-03T17:25:11Z

@CodeRabbit Please review this PR.

coderabbitai · 2026-03-03T17:25:27Z

@andreasmcdermott I'll review the changes in this PR.

✅ Actions performed

Review triggered.

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.

coderabbitai · 2026-03-03T17:25:38Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 957dd66 and 93e53b6.

⛔ Files ignored due to path filters (1)

package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (16)

.github/workflows/build_ecr_image.yml
.github/workflows/pipeline.yml
README.md
codedeploy/scripts/application_start.sh
docs/developers.md
docs/local-server.md
docs/oauth-proxy-implementation.md
package.json
src/auth/oauth-integration.test.ts
src/auth/oauth.test.ts
src/auth/provider.ts
src/client/shortcut.ts
src/server-http.test.ts
src/server-http.ts
src/tools/epics.test.ts
src/tools/iterations.test.ts

📝 Walkthrough

Walkthrough

This PR adds a full OAuth 2.0 (PKCE) proxy/provider flow and bearer-auth to the MCP server, refactors server session/client handling, introduces OAuth tests, updates CI/CD workflows, overhauls documentation and README, adjusts deployment script mounting, and updates package.json dependencies and scripts.

Changes

Cohort / File(s)	Summary
CI/CD Workflows `.github/workflows/build_ecr_image.yml`, `.github/workflows/pipeline.yml`	YAML trigger/formatting updates, added workflow_call/workflow_dispatch; pipeline restructured to call ECR build workflow, added build-scripts job, updated job dependencies and sha wiring.
OAuth Provider & Tests `src/auth/provider.ts`, `src/auth/oauth.test.ts`, `src/auth/oauth-integration.test.ts`	New OAuth provider factory with PKCE support, in-memory token cache + auto-refresh, client registration, callback handling, token exchange/refresh logic; comprehensive unit and integration tests added.
HTTP Server & Auth Integration `src/server-http.ts`, `src/server-http.test.ts`	Migrated from API-token model to Bearer OAuth flows: added requireBearerAuth, mcpAuthRouter, callback relay, session model changes (sessionToken/accessToken/clientWrapper), debug logging middleware, and transport/client wiring updates.
Shortcut Client Wrapper `src/client/shortcut.ts`	Added `updateClient(newClient)` to replace underlying Shortcut client and reset currentUser cache for token rotation.
Documentation `README.md`, `docs/developers.md`, `docs/local-server.md`, `docs/oauth-proxy-implementation.md`	Major README rewrite to emphasize hosted MCP/OAuth usage; new developer/local-server docs; detailed OAuth proxy implementation doc added; simplified troubleshooting/support sections.
Deployment Script `codedeploy/scripts/application_start.sh`	Added a readonly bind mount to inject `/opt/shortcut-mcp/.env` into container at `/usr/src/app/.env`.
Package Manifest `package.json`	Restructured root manifest: restored repository, removed author, new dependencies (express, jose, pino, zod, etc.), revised scripts and added peerDependencies.
Small Test Typing Fixes `src/tools/epics.test.ts`, `src/tools/iterations.test.ts`	Replaced `//` @ts-ignore with `// `@ts-expect-error for stricter compile-time assertions.

Sequence Diagram(s)

sequenceDiagram
    participant Client as AI Client (Cursor/Windsurf)
    participant MCP as MCP Server
    participant AuthSvr as Shortcut OAuth Server
    participant API as Shortcut API

    Client->>MCP: GET /.well-known/mcp-configuration (discovery)
    MCP->>Client: returns OAuth metadata

    Client->>MCP: GET /authorize (code_challenge)
    MCP->>AuthSvr: Redirect to upstream /authorize
    AuthSvr->>Client: Authorization page / consent
    Client->>AuthSvr: User approves -> redirect with code
    Client->>MCP: /oauth/callback (auth code)
    MCP->>AuthSvr: POST /token (exchange code for tokens)
    AuthSvr->>MCP: access_token + refresh_token
    MCP->>MCP: cache tokens, create session (accessToken + clientWrapper)
    Client->>MCP: POST /mcp/initialize (Bearer access_token)
    MCP->>API: validate token via Shortcut API (if needed)
    API->>MCP: token verification result
    MCP->>Client: session initialized / transport ready

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

SC-308993: tolerate stale rotated refresh tokens #163 — changes to token caching/refresh logic in src/auth/provider.ts.
sc-308937: Fix disabled Allow Access button in Codex OAuth flow #161 — changes to OAuth authorize flow and default scopes affecting provider request construction.
sc-308975: fix MCP transport error during Codex startup #162 — changes to bearer-token verification and session handling related to src/server-http.ts.

Suggested reviewers

opoku

Poem

🐰 Hopping through code with a joyful bound,
PKCE and tokens now safe and sound,
Redirects relayed, caches kept neat,
Bearer sessions ready — what a treat! 🥕

✨ Finishing Touches

📝 Generate docstrings (stacked PR)
📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch backup/token-refresh-redo

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai · 2026-03-03T17:28:32Z

@andreasmcdermott I'll review the changes in this PR.

✅ Actions performed

Review triggered.

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.

mdthorpe-sc added 9 commits February 19, 2026 11:02

biome schema fixed (revert)

27fcc06

Mixed merge conflict fix.

8c88cd6

Merging main

99db1f3

Merging main

65c2b74

Updated package-lock

eb24045

Added (back) token refresh logic when the server is handling sessions…

f815db3

… (http)

Linter fixes

76c6bb0

Unused ts-expect-error (Because nothing is being suppressed now)

bd416e7