Is it worth talking about the token_endpoint_auth_method param and how it influences this? As is it is unclear why an auth server will or won't issue a secret.

imo that gets too into the weeds. if we start explaining each optional branch, we'll end up with way too long of a post

This step combines the /authorize endpoint, the OAuth auth code callback handling, and the /token endpoint. If the audience isn't familiar with OAuth, this could be broken out into a few more steps.

+1 to include steps.

Good point, I can fix this.

Thoughts on using a library for this? panva/openid-client is a solid choice if so

Eeehhhh I am on the fence about this. As I mentioned in the doc, I am all for not reinventing the wheel here, but I wonder if for simple enough things like this a library-less approach is better. Open to your thoughts here @max-stytch

Well, we do say

Use off-the-shelf, well-tested, and secure libraries for things like token validation or authorization decisions.

and I think it is worth it on that front.
Additionally the internal mechanics of token introspection aren't really what we're here to talk about - it isn't an official part of the MCP protocol. Freeing up some cognitive space would allow us to talk about token introspection vs local jwt validation, for example.

A tool that shows using the caller's identity within the tool handler could work very well here. Even a simple whoami that echos the sub and the scope

Maybe? That would imply a more complex behavior, though, where now I need to pass authorization context into the tool, and that feels like a whole separate tutorial.

Without authorization context in the tool, or the ability to use the caller's information, we're not doing a good job of showing why OAuth is better than API Keys. Since we're using the requireBearerAuth helper, the auth info should be passed in to the tool automatically. Based off of this test we could do something like:

server.registerTool("whoami", {
    title: "Who Am I",
    description: "Retrieve authentication information about the current caller",
  },
  async ({}, { authInfo }, => ({
    content: [{ type: "text", text: `You are:\n${JSON.stringify(authInfo, null, 2)}` }]
  })
);

which could at least serve as a pointer to a separate future tutorial where we go further in depth on scope management

verify required scopes per route/tool on the resource server.

Can we show this above?

Likely a separate tutorial for authorization policies 😄

Are we considering only front-channel authorization? A client implementation might also use back-channel flows such as Device Code or CIBA.

Out of scope for this guide. There could be a multitude of authorization approaches, and we're only documenting what's outlined in the core spec.

If the access tokens are JWTs, we could validate them locally using the JWKS endpoint instead of calling introspection for every request. People who are not familiar with oauth might not know this.

Good call-out. I will mention that introspection is one of the ways but if the AS does not offer it, there are ways to do that locally.

It may be worth pointing to the spec security warning somewhere to clarify why we use CORS here, and e.g. add a comment that this is not production-ready. See also my test using the c# sdk.

For development and guide-purposes, I think using a localhost-uri is a better default than * (the latter effectively violating the spec), wdyt?

hmm I don't think CORS * violates that guideline? Those lines are about preventing DNS rebinding, but having * should be fine since we have auth here. CORS * is necessary if you want to allow web based clients.

Yeh, it should be fine, agreed. Auth + HTTPS mitigate most attack vectors. It's just that the spec clearly states MUST and all incoming connections, which is effectively not true, so one may be able to access e.g. the unprotected endpoints like PRM using dns rebind. But not worth building a repro with tools like lock.cmpxchg8b.com/rebinder.html now, so.. Nvm, maybe I am just too used to follow specs by the (RFC2119 key-) word. 😅

as with my origin-comment, we have a minor thing here. the spec states:

When implementing Streamable HTTP transport:

1. Servers MUST validate the Origin header on all incoming connections to prevent DNS rebinding attacks
2. When running locally, servers SHOULD bind only to localhost (127.0.0.1) rather than all network interfaces (0.0.0.0)
3. Servers SHOULD implement proper authentication for all connections

Now calling app.listen without a host effectively binds to 0.0.0.0 and should as such not be used in (security relevant) guides imo. WDYT?

I know it should be a prescriptive "starter" guide, but these small cracks might get copy/pasted everywhere (coming from the OIDC/OAuth world, this happened a lot and happens till today), so call me a burned child, but that's why I think it'd be better to give people good material from the start.

agree on listening on 127.0.0.1, think CORS is okay though (will comment on that)

What do you think about making this into a stateless MCP server? If we close the transport when the request closes, we don't need to manage transports in memory, or deal with sessions at all. We can leave stateful transports up to another guide.

  // Look Ma, No State!
  try {
    const server = getServer(req);
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
    });
    res.on('close', () => {
      console.log('Request closed');
      transport.close();
      server.close();
    });
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  } catch (error) {
    console.error('Error handling MCP request:', error);
    if (!res.headersSent) {
      res.status(500).json({
        jsonrpc: '2.0',
        error: {
          code: -32603,
          message: 'Internal server error',
        },
        id: null,
      });
    }
  }

thinking through whether we want to mention metadata probing... and my answer is no, let's leave it out. that can be an advanced topic. (no change needed here)

imo that gets too into the weeds. if we start explaining each optional branch, we'll end up with way too long of a post

(will test this): can we use 127.0.0.1 instead of needing to fetch the IP? if we're using the host ip, makes me think we'll need to worry about dns rebinding

Usually not. I've a working example here and the ip that reaches keycloak is my external ip.

(will test this): does this come from the resource parameter? if it comes from the scope, it might not offer the protection we want

It's from the scope, and a workaround until keycloak implements the rfcs. See here for status on that: keycloak/keycloak#41521

agree on listening on 127.0.0.1, think CORS is okay though (will comment on that)

hmm I don't think CORS * violates that guideline? Those lines are about preventing DNS rebinding, but having * should be fine since we have auth here. CORS * is necessary if you want to allow web based clients.