Skip to content

feat(mcp): wire up oauth2 token verification for streamable-http transport - #284

Open
Piotr1215 wants to merge 4 commits into
redis:mainfrom
Piotr1215:feat/mcp-oauth-token-verifier
Open

Piotr1215 wants to merge 4 commits into
redis:mainfrom
Piotr1215:feat/mcp-oauth-token-verifier

Conversation

@Piotr1215

@Piotr1215 Piotr1215 commented Apr 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem

The MCP SDK (v1.26.0+) has built-in OAuth 2.1 support via AuthSettings, TokenVerifier, and RequireAuthMiddleware. The agent-memory-server's existing auth.py handles JWT validation for the REST API (/v1/* endpoints), but the MCP streamable-http transport (/mcp endpoint) never wires this up to the SDK's auth layer.

When an MCP client (e.g., Claude) connects to /mcp without a Bearer token, the transport returns a 406 Not Acceptable error instead of 401 with a WWW-Authenticate header. Without that header, clients cannot discover the OAuth authorization server and the login flow never triggers.

The REST API and MCP transport are two separate ASGI apps — the FastAPI auth middleware on the REST side does not protect the MCP side.

Fix

Three small changes:

1. JWTTokenVerifier in mcp.py

Implements the SDK's TokenVerifier protocol by wrapping the existing verify_jwt() function from auth.py. Converts UserInfo (the REST API's auth model) to AccessToken (the SDK's auth model).

2. Conditional AuthSettings in mcp.py

_build_mcp_auth_kwargs() returns auth + token_verifier kwargs for FastMCP only when AUTH_MODE=oauth2 and OAUTH2_RESOURCE_HOST are set. When disabled, no kwargs are passed and behavior is unchanged.

When enabled, the SDK's built-in middleware:

  • Returns 401 with WWW-Authenticate: Bearer resource_metadata="..." for unauthenticated requests
  • Serves /.well-known/oauth-protected-resource automatically
  • Validates JWT tokens on all MCP requests via JWKS

3. /.well-known/oauth-authorization-server endpoint in main.py

RFC 9728 Protected Resource Metadata endpoint on the REST API side. Returns the resource server URL and authorization server URL so clients can discover where to authenticate.

4. OAUTH2_RESOURCE_HOST config setting

New optional setting for the server's public hostname (e.g., agent-memory.loft.rocks). Used to construct the resource field in metadata responses.

Configuration

# Enable MCP OAuth (in addition to existing REST API OAuth2 settings)
AUTH_MODE=oauth2
OAUTH2_ISSUER_URL=https://your-oidc-provider.example.com/
OAUTH2_RESOURCE_HOST=your-server.example.com
# Optional: OAUTH2_AUDIENCE for JWT audience validation (existing setting)

When AUTH_MODE is not oauth2 or OAUTH2_RESOURCE_HOST is unset, the MCP transport runs without auth — same as before this change.

Test plan

  • 53/53 existing auth tests pass
  • _build_mcp_auth_kwargs() returns correct settings when configured
  • _build_mcp_auth_kwargs() returns empty dict when unconfigured
  • curl -H "Accept: text/event-stream" https://server/mcp returns 401 + WWW-Authenticate header
  • MCP client (Claude) discovers OAuth flow and completes login
  • After login, MCP tools work with valid JWT

Tested with Ory Hydra as the OIDC provider and Claude as the MCP client.


Note

Medium Risk
Touches authentication and request routing for the MCP transport; misconfiguration or verifier/middleware integration issues could cause unexpected 401/406 behavior or block clients from connecting.

Overview
Wires the MCP streamable-http transport into the MCP SDK’s OAuth2 auth layer by conditionally passing AuthSettings and a new JWTTokenVerifier that adapts the server’s existing verify_jwt() validation to the SDK’s TokenVerifier interface.

Adds a new /.well-known/oauth-authorization-server endpoint on the REST app to publish protected-resource/authorization-server metadata (using new oauth2_resource_host config), and updates the MCP streamable_http_app() override to extend the parent app so auth middleware and well-known routes are preserved while still supporting namespace-prefixed routing.

Reviewed by Cursor Bugbot for commit 1f5dc32. Bugbot is set up for automated code reviews on this repo. Configure here.

Copilot AI review requested due to automatic review settings April 16, 2026 15:58

Copilot AI 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.

Pull request overview

This PR wires OAuth2 token verification into the MCP streamable-http transport so MCP clients receive proper 401 + WWW-Authenticate challenges and can complete OIDC discovery/login flows, aligning MCP auth behavior with the server’s existing JWT verification logic.

Changes:

  • Adds an MCP SDK TokenVerifier implementation that wraps the server’s existing verify_jwt() logic.
  • Conditionally enables MCP SDK auth middleware via AuthSettings when OAuth2 is configured.
  • Adds a well-known metadata endpoint and a new OAUTH2_RESOURCE_HOST setting for constructing resource URLs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File Description
agent_memory_server/mcp.py Adds JWTTokenVerifier and conditional auth wiring into FastMCP initialization.
agent_memory_server/main.py Adds a well-known OAuth discovery/metadata endpoint for clients.
agent_memory_server/config.py Introduces oauth2_resource_host configuration used for resource URL construction.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread V0/agent_memory_server/main.py Resolved
Comment thread V0/agent_memory_server/mcp.py Resolved
Comment thread V0/agent_memory_server/mcp.py Resolved
Comment thread V0/agent_memory_server/mcp.py Resolved
Comment thread V0/agent_memory_server/main.py Resolved
Comment thread V0/agent_memory_server/main.py Resolved
Comment thread V0/agent_memory_server/main.py Resolved
Comment thread V0/agent_memory_server/mcp.py Resolved
…sport

the mcp sdk (v1.26.0+) has built-in oauth 2.1 support via AuthSettings
and TokenVerifier, but the agent-memory-server never wired it up for the
streamable-http transport. without it, unauthenticated requests to /mcp
return 406 instead of 401 + WWW-Authenticate header, which prevents mcp
clients (like claude) from discovering the oauth flow.

changes:

- add JWTTokenVerifier that implements the sdk's TokenVerifier protocol
  by wrapping the existing verify_jwt() function
- conditionally pass AuthSettings + token_verifier to FastMCP when
  AUTH_MODE=oauth2 and OAUTH2_RESOURCE_HOST are set
- add /.well-known/oauth-authorization-server endpoint (RFC 9728) to
  the REST API for protected resource metadata discovery
- add OAUTH2_RESOURCE_HOST config setting for the server's public hostname

when enabled, the mcp transport now:
- returns 401 with WWW-Authenticate: Bearer resource_metadata="..." header
- serves /.well-known/oauth-protected-resource automatically (sdk built-in)
- validates jwt tokens on all mcp requests via jwks

when AUTH_MODE != oauth2 or OAUTH2_RESOURCE_HOST is unset, behavior is
unchanged — no auth kwargs are passed to FastMCP.

tested with ory hydra as the oidc provider and claude as the mcp client.
@Piotr1215
Piotr1215 force-pushed the feat/mcp-oauth-token-verifier branch from 2e0b5c7 to 1f5dc32 Compare April 16, 2026 16:05

@cursor cursor Bot left a comment

Copy link
Copy Markdown

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 and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

Fix All in Cursor

Reviewed by Cursor Bugbot for commit 1f5dc32. Configure here.

Comment thread V0/agent_memory_server/main.py Resolved
Upstream redis#319 moved the project into V0/, so the PR's edits to agent_memory_server/{config,main,mcp}.py conflicted on GitHub. Git rename detection carries them to V0/agent_memory_server/. The only other upstream change to these files since the branch point is the summary extraction fix in mcp.py (redis#316), which does not overlap the auth changes; both are kept.

Claude-Session: https://claude.ai/code/session_017edg9j5gLvdZkp32i7vPVD
test_list_sessions_returns_indexed_sessions failed on redis:latest only (expected 3 sessions, got 2). The PR does not touch working memory, and a sibling search index test flaked the same way on main in run 31640102621.

Claude-Session: https://claude.ai/code/session_017edg9j5gLvdZkp32i7vPVD
MCP clients can receive invalid discovery metadata, miss authentication configuration changes, or see service failures reported as invalid tokens. Synchronous key retrieval can also block other requests.

This branch has not been deployed

No deployments
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