ctx.auth inside tool callbacks when a tool needs the authenticated caller. It is present only when OAuth middleware authenticated the request, so guard before reading user fields.
This guide focuses on access-control patterns. Use the Auth API reference for the exact AuthInfo and UserInfo fields.
Guard authenticated tools
Return an authorization error before doing work that requires a user.Read identity fields
Usectx.auth.user.userId as the stable user identifier. Optional profile fields depend on the provider and granted scopes.
email, name, or provider-specific fields are always present. Check before using them in database keys or user-facing output.
Check scopes and permissions
Use scopes for OAuth grants and permissions for application authorization. mcp-use exposes both onctx.auth.
Scope data by organization or tenant
Many providers add organization or tenant claims toctx.auth.user. Narrow custom fields before using them.
Customize claim mapping
Use a provider’sgetUserInfo option when the token uses custom claim names or when you want normalized user fields across providers.
getUserInfo live under ctx.auth.user. Top-level ctx.auth.scopes and ctx.auth.permissions are derived from the verified payload, so your verifier or upstream token must include those claims when tools need them.
Next steps
Authentication
Choose and configure an OAuth provider.
Auth API reference
Look up
AuthInfo, UserInfo, and authorization helpers.Middleware
Apply shared authorization checks across tools.
Auth providers API reference
Look up provider-specific
getUserInfo options.