Include Authorization Info in Tool Calls (and request handlers generally)

[allenzhou101]

Includes the req.auth AuthInfo that's set by the MCP Server bearer auth middleware in the server request handler via SSE Transport, allowing for distinguishing of users in requests (eg. tool use).

Motivation and Context

When an MCP Server makes a tool call it may need to validate that a particular user has the authorization necessary to access a particular resource. For instance, the MCP Client could give any email it would like to the MCP Server, say to fetch audit logs of a project, but the Server should verify that the user has access to that particular project, which has to happen at the tool call level in the server.

This PR allows the developer to access the auth info not only in the initial /sse or /message route handlers but in the server request handler (eg. tool call) itself.

How Has This Been Tested?

Running an authenticated MCP Client session with a Server and validating that the extra param appears in the tool call with auth info.

This allows auth info to be easily used in a tool call:

export const createServer = () => {
    // Create server instance
    const server = new McpServer({
        name: "analytics",
        version: "1.0.0",
    });

    // Add get-schema tool
    server.tool(
        "get-schema",
        "Fetch the database schema",
        {},
        async (_, { authInfo }) => {
            const token = authInfo?.token;

            const scopes = authInfo?.scopes;
            if (!scopes || scopes && scopes.indexOf("get-schema") < 0) {
                return {
                    content: [
                        {
                            type: "text",
                            text: "Unauthorized: Missing get-schema scope",
                            code: 403
                        }
                    ]
                }
            }

import { z } from "zod";

/**
 * Information about a validated access token, provided to request handlers.
 */
export const AuthInfoSchema = z.object({
    /** The access token */
    token: z.string(),

    /** The client ID associated with this token */
    clientId: z.string(),

    /** Scopes associated with this token */
    scopes: z.array(z.string()),

    /** When the token expires (in seconds since epoch) */
    expiresAt: z.number().optional(),
});

export type AuthInfo = z.infer<typeof AuthInfoSchema>;

Breaking Changes

None.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

This allows for simpler access of auth data than simply including the session id in the transport since you'd have to handle mapping in that case: #158

Fixes #171

[cliffhall]

This all looks good, @allenzhou101. Could you add some unit tests?

[allenzhou101]

Sure, added!

[cliffhall]

This all looks good, builds, and tests run. It seems like a straightforward way to pass the AuthInfo to the individual tool requests. But I couldn't find any discussions or specs about this particular auth-related wrinkle. I would just like one or more of the core team to weigh in on the approach.

[jspahrsummers]

Thanks! I think this broadly makes sense and seems useful, but I'd like to tidy up the interface a little bit.

FWIW the motivation behind my comments is basically: we will have to maintain support for whatever API we land upon. Object types are better for this purpose than positional parameters (they can be extended arbitrarily later), and as a bonus, they are also more self-explanatory and clearer in usage.

Please also update from main and resolve any conflicts.

[cliffhall]

I think this still needs a few tweaks with regard to the extra object.

[allenzhou101]

@cliffhall Ah yes sorry, haven't had the chance to make the changes yet. Will lyk when done.

[apresmoi]

Hi, following this PR because I need something like this for the server I'm working on.

To understand how we might use this feature once merged, could you clarify these two points:

• Regarding the Authorization validation, is the expectation that the token will be a standard JWT? or we will be able to use any kind of string?
• How should the server-side validation logic be configured by the developer using the SDK? Will there be a callback option provided in ServerOptions to implement custom validation and return this AuthInfo?

Thank you!

[allenzhou101]

Hi, following this PR because I need something like this for the server I'm working on.

To understand how we might use this feature once merged, could you clarify these two points:

• Regarding the Authorization validation, is the expectation that the token will be a standard JWT? or we will be able to use any kind of string?
• How should the server-side validation logic be configured by the developer using the SDK? Will there be a callback option provided in ServerOptions to implement custom validation and return this AuthInfo?

Thank you!

This PR simply adds the ability for the auth key on the request object to be passed from HTTP to SSE sort of automatically, ultimately accessible in the tool call via the extra object. How you set the AuthInfo on that key is up to you--the most common case likely involving usage of the bearer middleware included in the sdk itself that sets this for you. You would likely just have a middleware function that takes the token, validates it, and then sets the auth key with the AuthInfo object.

[apresmoi]

Hi, following this PR because I need something like this for the server I'm working on.
To understand how we might use this feature once merged, could you clarify these two points:

• Regarding the Authorization validation, is the expectation that the token will be a standard JWT? or we will be able to use any kind of string?
• How should the server-side validation logic be configured by the developer using the SDK? Will there be a callback option provided in ServerOptions to implement custom validation and return this AuthInfo?

Thank you!

This PR simply adds the ability for the auth key on the request object to be passed from HTTP to SSE sort of automatically, ultimately accessible in the tool call via the extra object. How you set the AuthInfo on that key is up to you--the most common case likely involving usage of the bearer middleware included in the sdk itself that sets this for you. You would likely just have a middleware function that takes the token, validates it, and then sets the auth key with the AuthInfo object.

Oh, I had not seen the bearer middleware. I have aligned with this now, thank you! Eager for this PR to be merged, currently I have to do a weird mapping to identify the user in the tools/dataset.