MCP server separation into Authorization Server (AS) and Resource Server (RS) roles per spec PR #338 #982

ihrpr · 2025-06-18T21:13:06Z

Background: modelcontextprotocol/modelcontextprotocol#338
Closes: #921

MCP servers now act as Resource Servers (RS) only, not Authorization Servers
Implements RFC 9728 Protected Resource Metadata for AS discovery

Implementation:

Added TokenVerifier protocol to decouple token validation from OAuth provider logic
Resource Servers use token introspection to validate tokens with Authorization Servers
Added WWW-Authenticate header with resource_metadata parameter pointing to /.well-known/oauth-protected-resource

Example:

Split example into separate AS (auth_server.py) and RS (server.py) implementations
AS handles OAuth flows and token issuance
RS validates tokens via introspection and serves protected resources

Follow up:

remove github from Auth server examples, it brings too munch complexity
https://www.rfc-editor.org/rfc/rfc8707.html
refactor AnyHttpUrl

Kludex

Sorry for reviewing a draft, but I'm not sure if I'll have time to help further here.

src/mcp/client/auth.py

Kludex · 2025-06-20T08:23:04Z

src/mcp/server/auth/middleware/bearer_auth.py

+                "type": "http.response.start",
+                "status": status_code,
+                "headers": [
+                    (b"content-type", b"application/json"),


I don't think it makes sense for MCP to be using the low level ASGI API. I know it's not introduced in this PR, but it makes me sad. 😞

This is missing content-length btw.

examples/servers/simple-auth/mcp_simple_auth/auth_server.py

Kludex · 2025-06-20T08:29:49Z

examples/servers/simple-auth/mcp_simple_auth/auth_server.py

+@click.command()
+@click.option("--port", default=9000, help="Port to listen on")
+@click.option("--host", default="localhost", help="Host to bind to")
+def main(port: int, host: str) -> int:


This will give a lot of maintenance burden. People will ask a lot of uvicorn's parameters to be added here.

The purpose of this file is demonstrate mcp oauth concepts, not to be a production server. Removed the host as it's not needed, but port is useful

Ah, my bad. All good here.

examples/servers/simple-auth/mcp_simple_auth/github_oauth_provider.py

Kludex · 2025-06-20T08:31:51Z

examples/servers/simple-auth/mcp_simple_auth/legacy_as_server.py

+    # Server settings
+    host: str = "localhost"
+    port: int = 8000
+    server_url: AnyHttpUrl = AnyHttpUrl("http://localhost:8000")


Pydantic is appending a trailing slash on AnyHttpUrl - I think we should stop using AnyHttpUrl and use plain str in the whole code source.

Even if you are setting up http://localhost:8000, the real value will be http://localhost:8000/.

noted, this should be done outside of this PR, added to follow ups

Kludex · 2025-06-20T08:33:00Z

examples/servers/simple-auth/mcp_simple_auth/legacy_as_server.py

+    server_url: AnyHttpUrl = AnyHttpUrl("http://localhost:8000")
+    github_callback_path: str = "http://localhost:8000/github/callback"
+
+    def __init__(self, **data):


What is this for? Why is there no type hints?

Without the __init__, you get the error "Arguments missing for parameters 'github_client_id', 'github_client_secret'" because Pydantic expects these to be explicitly passed, not understanding they should come from environment variables. One option would be to just make then optional

That's the nature of BaseSettings. Is the idea that they can either be set programmatically or via env var?

yes, moved to optional. Using github in the example servers brings too much complexity, like having secrets etc, will remove it in the follow up PR.

src/mcp/server/auth/token_verifier.py

andreasoie · 2025-06-21T10:53:23Z

@ihrpr Hi! Thanks so much for driving this change, do you have any sense of when this PR might be merged? 🙏 (ballpark estimate)

pcarleton · 2025-06-23T11:16:52Z

src/mcp/server/auth/settings.py

@@ -15,9 +15,15 @@ class RevocationOptions(BaseModel):
 class AuthSettings(BaseModel):
    issuer_url: AnyHttpUrl = Field(
        ...,
-        description="URL advertised as OAuth issuer; this should be the URL the server " "is reachable at",
+        description="Base URL where this server is reachable. For AS: OAuth issuer URL. For RS: Resource server URL.",


issuer means something specific in OAuth parlance, so I'd prefer we not overload it here if we can avoid it. (mentioned here for AS metadata, and here for PRM metadata)

I put a commit here that changes this around: be4ddd3

I didn't push directly (still need to test it), but curious for your thoughts on that.

That means we'll always do the PRM endpoint, even if the server is an "all-in-one". (Which to clarify, all-in-one is still supported! but in that case we do want both the PRM and the AS metadata endpoints, the PRM will just point to itself.)

so with that change issuer_url will always be the URL of the authorization server.

The most unfortunate thing in that change is crafting the "server" URL, in order to put it in the www-authenticate and as the resource parameter.

I added a function to do it from host + port, but it feels a little jank. The other alternative would be to pass in a new parameter that's the server URL. lmkwyt

The other alternative would be to pass in a new parameter that's the server URL. lmkwyt

I think it's cleaner to have a parameter

rkondra-eightfold · 2025-06-23T12:00:13Z

@ihrpr @Kludex Is it possible to cleanup AuthSettings and the authorization server provider code ... MCP sdk doesn't need to have utils to implement auth server. This is too much unnecessary complexity, and looks very unclean. Can we please just point to existing libraries which implement oauth very well already https://github.com/authlib/authlib for Authorization server

ihrpr · 2025-06-23T12:12:08Z

@ihrpr @Kludex Is it possible to cleanup AuthSettings and the authorization server provider code ... MCP sdk doesn't need to have utils to implement auth server. This is too much unnecessary complexity, and looks very unclean. Can we please just point to existing libraries which implement oauth very well already https://github.com/authlib/authlib for Authorization server

With the new spec, MCP server acts as RS, so there is no need to support AS in the future, for now leaving it for backwards compatibility, and yes, ideally it should be cleaned up.

src/mcp/server/auth/settings.py

pcarleton

pending doc string, otherwise LGTM

ihrpr added 5 commits June 18, 2025 15:04

Implement separate Authorization Server (AS) / Resource Server (RS)

5c2097a

update readme

7ab353f

update comment

59d9bfd

server

e087e30

clean up

395c3ac

ihrpr requested a review from pcarleton June 18, 2025 21:13

fix tests

beef439

imfing mentioned this pull request Jun 19, 2025

Add OAuth Protected Resource Metadata support #807

Open

9 tasks

Kludex reviewed Jun 19, 2025

View reviewed changes

src/mcp/client/auth.py Outdated Show resolved Hide resolved

src/mcp/client/auth.py Outdated Show resolved Hide resolved

src/mcp/client/auth.py Outdated Show resolved Hide resolved

ihrpr added 10 commits June 19, 2025 11:07

add legacy mcp server as AS server for testing backwards compatibility

36d1e0d

json fix

f2e31ca

remove use of http clients in auth provider

8862507

refactor

90005e4

remove state machine, it overcomplicates things

86283c3

ruff

38c574f

fix comment

8080d87

comments

a565625

refactor legacy AS+MCP and AS examples

a8c99eb

improve comments

76dbf53

ihrpr marked this pull request as ready for review June 20, 2025 08:42

ihrpr marked this pull request as draft June 20, 2025 08:43

pyright and ruff

9b2e3df

ihrpr marked this pull request as ready for review June 20, 2025 08:49

Kludex reviewed Jun 20, 2025

View reviewed changes

ihrpr added 5 commits June 20, 2025 11:07

simplify server examples, address comments

926745a

remove host param from example servers

fd353c5

add readme

ef8d546

fix dependency

99e1db2

fix readme

a024ca8

LucaButBoring mentioned this pull request Jun 20, 2025

client_credentials grant type for mcp oauth #709

Open

pcarleton requested changes Jun 23, 2025

View reviewed changes

ihrpr added 2 commits June 23, 2025 12:52

make issuer_url auth server and add resource_server_url param

53431b8

fix readme

60507a6

ihrpr requested a review from pcarleton June 23, 2025 11:54

switch to uv commands

c72fbf7

pcarleton reviewed Jun 23, 2025

View reviewed changes

src/mcp/server/auth/settings.py Outdated Show resolved Hide resolved

pcarleton previously approved these changes Jun 23, 2025

View reviewed changes

fix description

dbed3df

ihrpr dismissed pcarleton’s stale review via dbed3df June 23, 2025 13:16

ihrpr merged commit 17f9c00 into main Jun 23, 2025
12 checks passed

ihrpr deleted the ihrpr/auth2 branch June 23, 2025 13:19

MCP server separation into Authorization Server (AS) and Resource Server (RS) roles per spec PR #338 #982

MCP server separation into Authorization Server (AS) and Resource Server (RS) roles per spec PR #338 #982

Conversation

ihrpr commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kludex left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ihrpr Jun 20, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kludex Jun 20, 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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

andreasoie commented Jun 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rkondra-eightfold commented Jun 23, 2025

Uh oh!

ihrpr commented Jun 23, 2025

Uh oh!

Uh oh!

pcarleton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ihrpr commented Jun 18, 2025 •

edited

Loading

ihrpr Jun 20, 2025 •

edited

Loading

Kludex Jun 20, 2025 •

edited

Loading