Front-Door Auth by EricGustin · Pull Request #696 · ArcadeAI/arcade-mcp

EricGustin · 2025-11-25T02:59:32Z

Valuable references for the reviewer:

Docs PR: Add docs for server-level auth docs#583
Implements Phase 1 of the following planning doc: https://linear.app/arcadedev/project/arcade-mcp-supports-mcp-auth-front-door-auth-7cbaa20cb054/overview

demovideo.mp4

PR Description

Adds OAuth 2.1 Resource Server authentication to arcade-mcp-server, enabling HTTP MCP servers to validate Bearer tokens on every request. This unlocks tool-level authorization and secrets support for HTTP servers.

Multiple authorization server support
Granular token validation options (verify_exp, verify_iat, verify_iss)
Environment variable configuration
OAuth discovery metadata endpoint (/.well-known/oauth-protected-resource)
Extracts sub claim from token as context.user_id
Lifts transport restrictions for tools requiring auth/secrets on HTTP when protected

from arcade_mcp_server import MCPApp
from arcade_mcp_server.resource_server import ResourceServerAuth, AuthorizationServerEntry

resource_server_auth = ResourceServerAuth(
    canonical_url="http://127.0.0.1:8000/mcp",
    authorization_servers=[
        AuthorizationServerEntry(
            authorization_server_url="https://auth.example.com",
            issuer="https://auth.example.com",
            jwks_uri="https://auth.example.com/jwks",
        )
    ],
)

app = MCPApp(name="my_server", version="1.0.0", auth=resource_server_auth)

Testing

Beyond the comprehensive unit tests, I also manually tested end-to-end with WorkOS Authkit (DCR) and KeyCloak (non-DCR).

Future Work

CIMD support
An ArcadeResourceServer to make adding front-door auth super easy when using Arcade's Auth Server

Note

Adds OAuth 2.1 front-door auth (JWKS validation + OAuth discovery) and propagates user identity to tools, enabling auth/secret-requiring tools over HTTP.

Authentication (Front-Door OAuth 2.1)
- New resource_server module with ResourceServerAuth (multi-authorization-server, metadata) and JWKSTokenValidator (JWKS-based JWT validation) plus granular validation options.
- ASGI ResourceServerMiddleware validates Bearer tokens on every HTTP request and injects resource_owner.
- OAuth discovery endpoint via FastAPI router at /.well-known/oauth-protected-resource[/<path>].
Integration
- MCPApp/worker accept auth/resource_server_validator, mount middleware, expose discovery; logs accepted auth servers.
- HTTP transport (http_streamable) carries SessionMessage with resource_owner from request → session.
- Context/Session/Server plumb resource_owner; Server selects user_id preferring token sub.
Behavior Changes
- HTTP transport restriction lifted for tools requiring authorization/secrets when request is authenticated; otherwise blocked with actionable error.
Configuration
- Env-var based auth config via MCP_RESOURCE_SERVER_* in MCPSettings.ResourceServerSettings; .env auto-load.
Telemetry
- Usage tracking records resource_server_type on server start.
Examples
- New examples/mcp_servers/authorization sample server (HTTP auth, secrets, Reddit tool) with Docker setup.
Tests
- Extensive unit tests for validators, middleware, env config, multi-AS, transport rules, and app integration.
Version
- Bump arcade-mcp-server to 1.12.0; minor docstring tweak in __init__.py.

^{Written by Cursor Bugbot for commit d1116cd. This will update automatically on new commits. Configure here.}

Resolves TOO-152

codecov · 2025-11-25T03:01:03Z

Codecov Report

❌ Patch coverage is 77.77778% with 86 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...cp-server/arcade_mcp_server/fastapi/auth_routes.py	26.92%	19 Missing ⚠️
...er/arcade_mcp_server/resource_server/middleware.py	78.57%	12 Missing ⚠️
...cade_mcp_server/resource_server/validators/jwks.py	88.04%	11 Missing ⚠️
...bs/arcade-mcp-server/arcade_mcp_server/settings.py	65.62%	11 Missing ⚠️
libs/arcade-mcp-server/arcade_mcp_server/worker.py	55.55%	8 Missing ⚠️
libs/arcade-mcp-server/arcade_mcp_server/server.py	69.56%	7 Missing ⚠️
...ibs/arcade-mcp-server/arcade_mcp_server/mcp_app.py	54.54%	5 Missing ⚠️
...er/arcade_mcp_server/transports/http_streamable.py	63.63%	4 Missing ⚠️
...p-server/arcade_mcp_server/usage/server_tracker.py	40.00%	3 Missing ⚠️
...p-server/arcade_mcp_server/resource_server/base.py	95.83%	2 Missing ⚠️
... and 2 more

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This PR implements "Front-Door Authentication" for the Arcade MCP server, adding OAuth 2.1-compliant server-level authentication for HTTP transport. The implementation validates Bearer tokens on every HTTP request before processing MCP protocol messages, enabling secure HTTP transport with tool-level authorization and OAuth discovery support.

Key Changes:

Added JWT-based token verification with JWKS support for validating Bearer tokens
Implemented OAuth 2.0 Protected Resource Metadata (RFC 9728) for client discovery
Added support for multiple authorization servers with flexible configuration via environment variables or code

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
libs/tests/arcade_mcp_server/test_server_auth.py	Comprehensive test suite for JWT verification, RemoteOAuthProvider, middleware, and multi-authorization server scenarios
libs/tests/arcade_mcp_server/test_server.py	Added authenticated user context to HTTP transport tests
libs/tests/arcade_mcp_server/test_mcp_app.py	Updated tests to include server_auth_provider parameter
libs/arcade-mcp-server/pyproject.toml	Added python-jose and httpx dependencies
libs/arcade-mcp-server/arcade_mcp_server/worker.py	Integrated auth middleware and OAuth discovery routes
libs/arcade-mcp-server/arcade_mcp_server/types.py	Extended SessionMessage to carry authenticated user info
libs/arcade-mcp-server/arcade_mcp_server/transports/http_streamable.py	Modified to extract and pass authenticated user from scope
libs/arcade-mcp-server/arcade_mcp_server/settings.py	Added ServerAuthSettings for environment-based configuration
libs/arcade-mcp-server/arcade_mcp_server/session.py	Updated to handle authenticated user context per request
libs/arcade-mcp-server/arcade_mcp_server/server_auth/	New module with base classes, JWT verifier, RemoteOAuthProvider, and ASGI middleware
libs/arcade-mcp-server/arcade_mcp_server/server.py	Enhanced to use authenticated user from front-door auth for tool context
libs/arcade-mcp-server/arcade_mcp_server/mcp_app.py	Added auth parameter and removed duplicate .env loading
libs/arcade-mcp-server/arcade_mcp_server/fastapi/auth_routes.py	OAuth discovery endpoint implementation
libs/arcade-mcp-server/arcade_mcp_server/context.py	Added authenticated_user to Context initialization
examples/mcp_servers/authorization/	Complete example server demonstrating front-door auth with Docker setup

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

cursor

This PR is being reviewed by Cursor Bugbot

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

wdawson · 2025-12-04T18:48:03Z

+      - ARCADE_SERVER_TRANSPORT=http
+      - ARCADE_SERVER_HOST=0.0.0.0
+      - ARCADE_SERVER_PORT=8001
+      - MCP_RESOURCE_SERVER_CANONICAL_URL=http://127.0.0.1:8080/mcp


probably out of scope of this PR, but I've generally seen this as PROXY_URL or something for when the server is behind a proxy of any kind.

wdawson

Auth stuff looks good to me! Some optimization potential in a comment!

I did not really review the devex side. I figure you want a non-auth person to do that

wdawson · 2025-12-05T00:00:43Z

+        Returns:
+            Dictionary containing resource metadata per RFC 9728
+        """
+        return {


Assuming this doesn't change, I would construct this at init time so that it can be returned very efficiently.

Then, some other values to consider adding to the document now:

scopes_supported: Should contain the scopes required to access the MCP server itself (maybe just mcp?; not the tool scopes! — seems like we aren't validating scopes at all right now though, so maybe not worth it!

bearer_methods_supported: Probably just header?

And some more to consider in the future:

resource_name: A human readable name to display to the end user; could be settable by some config somewhere?

resource_documentation: A URL for docs about this MCP server; config?

resource_policy_uri: A URL for a human readable policy document; config?

resource_tos_uri: A URL for terms of service; config?

Thanks! I implemented the following:

construct resource metadata at init time

added bearer_methods_supported

For the others:

Holding off on scopes entirely for now

Will add a mention of resource_* to planning document for phase 2

nbarbettini · 2025-12-10T19:00:16Z

+# ```
+# resource_server = ResourceServer()
+
+app = MCPApp(name="authorization", version="1.0.0", log_level="DEBUG", auth=resource_server)


very nitty nit: It feels weird to pass a ResourceServer to auth, because what I'm building here (the MCP server) is a resource server. Maybe ResourceServerAuthorization as a class name instead?

Not nitty at all! I'm going to go with ResourceServerAuth

nbarbettini · 2025-12-10T19:16:55Z

+    that are not compliant with MCP.
+
+    Note: Token signature verification is always enabled and cannot be disabled.
+    Additionally, the subject (sub claim) must always be present in the token.


We may have to lift the sub claim requirement - we'll see. Some AS don't return it, or return some non-standard claim name. I think it's OK to make this required for now.

nbarbettini · 2025-12-11T19:51:26Z

            issuer="https://your-workos.authkit.app",
            jwks_uri="https://your-workos.authkit.app/oauth2/jwks",
-            validation_options=AccessTokenValidationOptions(verify_aud=False),
+            expected_audiences=["your-authkit-client-id"],  # Override expected aud claim


nit: from what we were discussing yesterday it seems like in the WorkOS case it's an app or workspace ID, not a client ID right?

So their naming of things is very bad, but it is the AuthKit's Client ID (which is closer to a workspace ID), not the registered client's ID. Both IDs are unfortunately prefixed with client_ lol

EricGustin added 14 commits November 7, 2025 12:01

WIP

9e83804

Haha it actually kinda works

beb871d

Protected HTTP server with tool-level auth working

7e6e56c

Generalize remote oauth provider and some cleanup

59699f3

Intermediary commit

9ca3bba

Add auth env var configuration

58b13c0

Use python-jose instead of pyjwt

0c99777

multi-algorithm, multi-issuer, client_id extraction

b96b635

Merge branch 'main' into ericgustin/front-door-auth

0c8932c

Support 1 or more AS

428dcc5

Solve envvar chicken & egg problem

0fd488d

Merge branch 'main' into ericgustin/front-door-auth

172acfc

Cleanup part 1

86bbc6d

Cleanup Part 2

078c81f

EricGustin requested a review from Copilot November 25, 2025 03:01

Copilot AI reviewed Nov 25, 2025

View reviewed changes

Comment thread libs/arcade-mcp-server/arcade_mcp_server/settings.py

EricGustin added 3 commits November 24, 2025 22:36

Module wide renaming

ae81885

Add logs

5a5f98c

Track ResourceServerValidator type

1c49833

EricGustin mentioned this pull request Dec 2, 2025

Add docs for server-level auth ArcadeAI/docs#583

Merged

Use keycloak as an example

1b311f0

EricGustin marked this pull request as ready for review December 3, 2025 00:08

Update some examples

570053d

cursor Bot reviewed Dec 3, 2025

View reviewed changes

Comment thread libs/arcade-mcp-server/arcade_mcp_server/server.py

Fix bug

810d337

cursor Bot reviewed Dec 3, 2025

View reviewed changes

Comment thread libs/arcade-mcp-server/arcade_mcp_server/session.py Outdated

Comment thread libs/arcade-mcp-server/arcade_mcp_server/resource_server/middleware.py Outdated

401 response

c696d76

cursor Bot reviewed Dec 4, 2025

View reviewed changes

Comment thread libs/arcade-mcp-server/arcade_mcp_server/resource_server/middleware.py

Comment thread libs/arcade-mcp-server/arcade_mcp_server/resource_server/middleware.py Outdated

Update resource metadata url construction

b0a26c2

This comment was marked as off-topic.

Sign in to view

wdawson reviewed Dec 4, 2025

View reviewed changes

wdawson approved these changes Dec 5, 2025

View reviewed changes

Resolve merge conflicts

6d9c1ca

cursor Bot reviewed Dec 5, 2025

View reviewed changes

Comment thread libs/arcade-mcp-server/arcade_mcp_server/fastapi/auth_routes.py

Comment thread libs/arcade-mcp-server/arcade_mcp_server/settings.py

EricGustin added 2 commits December 5, 2025 14:25

Address comments

3c120af

Make protected resource API response more robust

0b16721

nbarbettini reviewed Dec 10, 2025

View reviewed changes

EricGustin added 2 commits December 10, 2025 14:20

Merge branch 'main' into ericgustin/front-door-auth

fe4f418

Address comments

571f666

cursor Bot reviewed Dec 11, 2025

View reviewed changes

Comment thread examples/mcp_servers/simple/pyproject.toml Outdated

EricGustin added 2 commits December 10, 2025 16:26

Rename ResourceServer --> ResourceServerAuth

5c0056b

Bump arcade_mcp_server version

070443d

EricGustin requested a review from nbarbettini December 11, 2025 19:38

nbarbettini approved these changes Dec 11, 2025

View reviewed changes

Words

d1116cd

EricGustin merged commit 98fd13c into main Dec 11, 2025
14 checks passed

Uh oh!

Conversation

EricGustin commented Nov 25, 2025 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Valuable references for the reviewer:

PR Description

Testing

Future Work

Uh oh!

codecov Bot commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

This PR is being reviewed by Cursor Bugbot

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as off-topic.

Uh oh!

wdawson Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

wdawson left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wdawson Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

EricGustin Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nbarbettini Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

EricGustin Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nbarbettini Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nbarbettini Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

EricGustin Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

EricGustin commented Nov 25, 2025 •

edited by cursor Bot

Loading

codecov Bot commented Nov 25, 2025 •

edited

Loading

wdawson left a comment •

edited

Loading

EricGustin Dec 5, 2025 •

edited

Loading