feat: add OAuth 2.0 authentication for remote MCP access by nix-tkobayashi · Pull Request #104 · nulab/backlog-mcp-server

nix-tkobayashi · 2026-04-28T17:46:37Z

Closes #105

Summary

Add OAuth 2.0 support so the MCP server can be securely exposed over a network with per-user Backlog authentication, eliminating the need for a shared API key.

Implements the MCP Third-Party Authorization Flow using Hono (consistent with existing codebase)
Server acts as both an OAuth authorization server (for MCP clients) and an OAuth client (for Backlog)
Supports Dynamic Client Registration (RFC 7591), Authorization Server Metadata (RFC 8414), Protected Resource Metadata (RFC 9728), and PKCE (S256)
Fully opt-in: enabled only when BACKLOG_OAUTH_CLIENT_ID is set — existing stdio and local HTTP modes are unchanged
43 new tests (6 test files), all passing alongside existing test suite

Motivation

When using the MCP server remotely (e.g., deployed on a cloud server), sharing a single API key is a security concern. OAuth 2.0 lets each user authenticate with their own Backlog account, providing proper access control and auditability.

New files

File	Purpose
`src/auth/backlogOAuthConfig.ts`	Parses OAuth env vars, opt-in detection
`src/auth/backlogAuthContext.ts`	AsyncLocalStorage for per-request access token
`src/auth/tokenStore.ts`	In-memory store for pending auths, auth codes, clients, verification cache
`src/auth/backlogOAuthClient.ts`	HTTP calls to Backlog OAuth API
`src/auth/oauthRoutes.ts`	Hono routes for all OAuth endpoints
`src/auth/bearerAuthMiddleware.ts`	Bearer token validation middleware for `/mcp`

Modified files

File	Change
`src/httpMcpServer.ts`	Conditionally mount OAuth routes & middleware, pass `authInfo` to transport
`src/index.ts`	Detect OAuth config, create OAuth client registry when enabled
`src/utils/backlogClientRegistry.ts`	Add `createOAuthBacklogClientRegistry()` using AsyncLocalStorage tokens
`.env.example`	Add OAuth env var documentation
`README.md` / `README.ja.md`	Add OAuth setup documentation

How to test

Register an OAuth application in Backlog (Personal Settings → Register Application)
Set env vars: BACKLOG_OAUTH_CLIENT_ID, BACKLOG_OAUTH_CLIENT_SECRET, BACKLOG_DOMAIN, MCP_SERVER_BASE_URL
Start with --transport http
Verify metadata: curl <base>/.well-known/oauth-authorization-server
Register a client: POST /register
Complete the authorize → callback → token flow
Use the access token with Authorization: Bearer <token> on /mcp

Test plan

All 43 new OAuth tests pass
All 369 existing tests pass (80 test files)
End-to-end OAuth flow verified against live Backlog instance
Backward compatibility: stdio and local HTTP without OAuth unchanged

🤖 Generated with Claude Code

Enable per-user Backlog OAuth authentication when exposing the MCP server over a network, removing the need for shared API keys. Implements the MCP Third-Party Authorization Flow (RFC 8414, RFC 9728, RFC 7591) with PKCE (S256) support. The server acts as both an OAuth authorization server for MCP clients and an OAuth client for Backlog. OAuth is opt-in: set BACKLOG_OAUTH_CLIENT_ID to enable. Existing stdio and local HTTP modes continue to work unchanged. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Address review feedback: - Generate opaque access/refresh tokens; keep Backlog tokens server-side - Validate redirect_uris (require https or http://localhost) - Accept and validate the resource parameter per MCP spec - Add client registration limit (max 1000) and periodic store cleanup - Document single-org limitation and in-memory store constraint Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…h rollback - Add 90-day TTL to registered clients with eviction when MAX_CLIENTS reached - Forward Backlog authorization errors (e.g. user denial) to MCP client redirect_uri - Restore refresh token on upstream refresh failure to prevent token loss - Validate token_endpoint_auth_method against supported methods - Add resource parameter validation in token exchange - Add refresh token expiry (30-day TTL) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add URLSearchParams, fetch, setInterval, clearInterval, setTimeout to ESLint globals to fix no-undef errors in CI. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

…en exchange Apply Host header validation to all routes (not just /mcp) to prevent DNS rebinding on OAuth endpoints. Make redirect_uri required in the authorization_code token exchange per RFC 6749 §4.1.3. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

katayama8000 · 2026-05-15T11:51:43Z

@nix-tkobayashi
Thanks for your contribution.
This looks like a great PR for the remote MCP server.
I'll take a look it.

nix-tkobayashi · 2026-05-15T13:50:08Z

@katayama8000
Thank you for reviewing!
We've already deployed the remote MCP server in our organization and have been actively using it.
Happy to address any feedback you may have.

…tests

katayama8000 · 2026-05-26T12:31:52Z

+  });
+
+  // Authorization Endpoint
+  app.on(['GET', 'POST'], '/authorize', async (c) => {


@nix-tkobayashi
POST should be acceptable here?

Good point — POST is optional per RFC 6749 §3.1, and all known MCP clients (Claude Desktop, Cursor, etc.) use browser redirects (GET) to reach /authorize. There's no concrete use case requiring POST here, so I've changed it to app.get('/authorize', ...) to keep the surface area minimal. Fixed in 76dee52.

katayama8000 · 2026-05-26T12:53:10Z

@nix-tkobayashi
I fixed some and left a comment. Other than that, looks good to me.
I’ll test it locally and merge it later.
Can you check the comments I left?

…improved readability

POST is not required by RFC 6749 or the MCP spec, and all known MCP clients (Claude Desktop, Cursor, etc.) use browser redirects (GET). Removing POST simplifies the implementation and reduces attack surface. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

nix-tkobayashi · 2026-05-26T13:44:46Z

@katayama8000 Thanks for the review and the fixes! I addressed the comment you left and updated /authorize to accept GET only. All tests are passing now. Please let me know if you spot anything else, and thanks in advance for testing it locally.

nix-tkobayashi and others added 6 commits April 29, 2026 02:46

fix: add missing Node.js globals to ESLint config

7d9873a

Add URLSearchParams, fetch, setInterval, clearInterval, setTimeout to ESLint globals to fix no-undef errors in CI. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

style: apply Prettier formatting to OAuth and related files

38adc9c

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

nix-tkobayashi and others added 2 commits May 18, 2026 22:01

Merge branch 'main' into feat/oauth-remote-mcp

e7ed0db

feat: refactor TokenStore to use factory function and update related …

f625370

…tests

katayama8000 reviewed May 26, 2026

View reviewed changes

katayama8000 and others added 2 commits May 26, 2026 21:55

feat: format storePendingAuth and storeMcpRefreshToken functions for …

08e6904

…improved readability

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add OAuth 2.0 authentication for remote MCP access#104

feat: add OAuth 2.0 authentication for remote MCP access#104
nix-tkobayashi wants to merge 10 commits into
nulab:mainfrom
nix-tkobayashi:feat/oauth-remote-mcp

nix-tkobayashi commented Apr 28, 2026 •

edited

Loading

Uh oh!

katayama8000 commented May 15, 2026 •

edited

Loading

Uh oh!

nix-tkobayashi commented May 15, 2026

Uh oh!

katayama8000 May 26, 2026

Uh oh!

nix-tkobayashi May 26, 2026

Uh oh!

katayama8000 commented May 26, 2026

Uh oh!

nix-tkobayashi commented May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

nix-tkobayashi commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

New files

Modified files

How to test

Test plan

Uh oh!

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

Uh oh!

Uh oh!

nix-tkobayashi commented May 15, 2026

Uh oh!

katayama8000 May 26, 2026

Choose a reason for hiding this comment

Uh oh!

nix-tkobayashi May 26, 2026

Choose a reason for hiding this comment

Uh oh!

katayama8000 commented May 26, 2026

Uh oh!

nix-tkobayashi commented May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nix-tkobayashi commented Apr 28, 2026 •

edited

Loading

katayama8000 commented May 15, 2026 •

edited

Loading