import { type AuthInfo, type BaseContext } from '@modelcontextprotocol/server'; import { type JWTPayload } from 'jose'; /** * The MCP SDK's `AuthInfo`, extended with the guarantees mcp-auth provides after successful JWT * verification: * * - `issuer`: the verified `iss` claim — always the configured trusted authorization server * - `subject`: the verified `sub` claim, identifying the end user or client (required, per * RFC 9068) * - `claims`: the full verified JWT payload for access to any custom claims */ export type McpAuthInfo = AuthInfo & { /** The issuer of the token (the `iss` claim). */ issuer: string; /** The subject of the token (the `sub` claim), typically the user ID. */ subject: string; /** The full verified JWT payload. */ claims: JWTPayload; }; /** * Checks whether an `AuthInfo` object carries the mcp-auth guarantees ({@link McpAuthInfo}), * i.e. it was produced by `MCPAuth#verifyAccessToken`. */ export declare const isMcpAuthInfo: (info: AuthInfo) => info is McpAuthInfo; export type GetAuthInfoOptions = { /** * Scopes the access token must include, for per-tool authorization on top of the * endpoint-level `requiredScopes` of the SDK's `requireBearerAuth`. * * When any are missing, an {@link MCPAuthError} with code `'missing_required_scopes'` is * thrown. The MCP SDK converts errors thrown in tool callbacks into tool error results * (`isError: true`), so the model receives a graceful `insufficient_scope: ...` refusal * instead of a failed request. */ requiredScopes?: string[]; }; /** * Extracts the verified {@link McpAuthInfo} from an MCP request handler context (e.g. a tool * callback's second argument), optionally enforcing per-tool scopes. * * The bearer-auth middleware guarantees the auth info is present on every authenticated HTTP * request, so a missing value indicates a wiring problem — for example, the MCP endpoint is not * protected by `requireBearerAuth`, or a different token verifier than `MCPAuth` is in use. * * @example * ```ts * import { getAuthInfo } from 'mcp-auth'; * * server.registerTool('whoami', { description: 'Get the current user' }, (ctx) => { * const { subject, claims } = getAuthInfo(ctx); * return { content: [{ type: 'text', text: JSON.stringify({ subject, claims }) }] }; * }); * * server.registerTool('purge-notes', { description: 'Delete every note' }, (ctx) => { * // Throws unless the token has the `notes:write` scope; the SDK surfaces the error to the * // model as a tool error result. * const { subject } = getAuthInfo(ctx, { requiredScopes: ['notes:write'] }); * // ... * }); * ``` * * @param context The request handler context provided by the MCP SDK. * @param options Optional per-tool authorization requirements. * @returns The verified auth info. * @throws {MCPAuthError} if the context has no auth info, the auth info was not produced by * `MCPAuth#verifyAccessToken`, or a required scope is missing. */ export declare const getAuthInfo: (context: BaseContext, options?: GetAuthInfoOptions) => McpAuthInfo;