Skip to main content
Use 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.
If every tool in a group needs the same rule, use middleware. If only one tool needs the rule, keep the check in the tool.

Read identity fields

Use ctx.auth.user.userId as the stable user identifier. Optional profile fields depend on the provider and granted scopes.
Do not assume 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 on ctx.auth.
Providers map claims differently. Check the provider page for claim conventions and use the API reference for the exact helper functions.

Scope data by organization or tenant

Many providers add organization or tenant claims to ctx.auth.user. Narrow custom fields before using them.
Use provider-specific claim names consistently in your app. For example, Clerk and WorkOS expose organization context with different field names.

Customize claim mapping

Use a provider’s getUserInfo option when the token uses custom claim names or when you want normalized user fields across providers.
Fields returned from 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.