user://profile

Purpose

Authenticated user profile information

Description

The user://profile resource exposes the currently authenticated user's profile information extracted from their JWT token. It provides structured access to user identity data including user ID, email, display name, and group memberships.

This resource is useful for:

• Displaying user information in UI components
• Checking user's group memberships for permission decisions
• Personalizing responses based on user data
• Verifying authentication status programmatically
• Building user-aware features

Unlike the user-info tool which returns formatted text, this resource provides structured JSON data for programmatic use.

Resource Details

URI: user://profile

MIME Type: application/json

Authentication Required: Yes (JWT token)

This resource requires a valid JWT token and will return an error if accessed without authentication or if AUTH_REQUIRED=false in the server configuration.

Example Usage

Ask Claude:

"Read my user profile resource"
"Show me the user://profile data"
"What's in my user profile?"
"Get my user information from the resource"

Response Structure

{
  "userId": "user-123",
  "email": "developer@example.com",
  "name": "Jane Developer",
  "groups": ["admin", "developers", "users"],
  "metadata": {
    "hasEmail": true,
    "hasName": true,
    "groupCount": 3
  }
}

Response Fields

userId (required)

Type: string

The user's unique identifier from the JWT token's sub claim. This is the primary key for identifying the user across systems.

Examples:

• "user-123"
• "auth0|5f8e7d6c9b"
• "google-oauth2|123456789"

email (optional)

Type: string | null

The user's email address from the JWT token's email claim.

When null: The IdP didn't provide an email claim in the token.

Examples:

• "developer@example.com"
• "user@company.com"
• null (if not provided)

name (optional)

Type: string | null

The user's display name from the JWT token's name claim.

When null: The IdP didn't provide a name claim. The system may fall back to email or user ID for display.

Examples:

• "Jane Developer"
• "Dr. John Smith"
• null (if not provided)

groups (optional)

Type: string[] | null

Array of group names or roles the user belongs to, from the JWT token's groups claim (or equivalent).

When null: The IdP didn't provide group information.

Examples:

• ["admin", "developers", "users"]
• ["premium", "beta-testers"]
• null (if not provided)

metadata

Type: object

Helpful metadata about what data is available:

• hasEmail (boolean): Whether email field is present
• hasName (boolean): Whether name field is present
• groupCount (number): Number of groups (0 if none)

This helps clients quickly check data availability without null checks.

Common Use Cases

Display User Information

Read user://profile
→ Show user.name in header
→ Display user.email in menu
→ Show "Logged in as {name}"

Permission Checking

const profile = await readResource("user://profile");
const isAdmin = profile.groups?.includes("admin");

if (isAdmin) {
  // Show admin features
  showAdminPanel();
}

Personalization

const profile = await readResource("user://profile");

// Customize greeting
const greeting = profile.name
  ? `Welcome back, ${profile.name}!`
  : `Welcome back!`;

// Show relevant content for user's groups
const relevantContent = filterByGroups(profile.groups);

Authentication Verification

try {
  const profile = await readResource("user://profile");
  // User is authenticated
  showAuthenticatedUI();
} catch (error) {
  // Not authenticated or token invalid
  redirectToLogin();
}

Resource Access Pattern

Reading the Resource

MCP clients read this resource using the resources/read request:

{
  "method": "resources/read",
  "params": {
    "uri": "user://profile"
  }
}

The server responds with:

{
  "contents": [
    {
      "uri": "user://profile",
      "mimeType": "application/json",
      "text": "{\"userId\":\"user-123\",\"email\":\"developer@example.com\",...}"
    }
  ]
}

Subscribing to Updates

Clients can subscribe to be notified when the user profile changes:

{
  "method": "resources/subscribe",
  "params": {
    "uri": "user://profile"
  }
}

Profile changes occur when:

• User logs in as different account
• Token is refreshed with updated claims
• User's groups/roles are modified

Authentication Requirements

Valid JWT Token

The resource requires:

• Valid JWT token in the Authorization header
• Token not expired
• Token signed by trusted IdP (verified via JWKS)

AUTH_REQUIRED Setting

If AUTH_REQUIRED=false in server configuration:

• Authentication is disabled
• This resource returns an error
• Use the config://server resource to check if auth is enabled

Error Responses

No Token Provided:

{
  "error": "User context not available. Authentication may be disabled or user data not present."
}

Invalid Token:

{
  "error": "Invalid authentication token"
}

Token Expired:

{
  "error": "Token has expired"
}

JWT Token Claims

The resource extracts data from standard JWT claims:

Claim	Maps To	Required
sub	userId	Yes
email	email	No
name	name	No
groups	groups	No

Some IdPs use different claim names (e.g., roles instead of groups). The server configuration can be adjusted to map custom claims.

Handling Optional Fields

Since email, name, and groups are optional, always check before using:

const profile = await readResource("user://profile");

// Check using metadata
if (profile.metadata.hasEmail) {
  showEmail(profile.email);
}

// Or check directly
if (profile.name) {
  greetByName(profile.name);
} else if (profile.email) {
  greetByEmail(profile.email);
} else {
  genericGreeting();
}

// Groups may be null or empty array
const groups = profile.groups || [];
const isAdmin = groups.includes("admin");

Security Considerations

Data Source

All data comes from the JWT token:

• Trust depends on IdP security
• Claims are validated by server
• Token signature verified via JWKS
• No additional database lookups

Sensitive Information

The resource only exposes claims from the JWT token. Ensure your IdP doesn't include sensitive information in tokens like:

• Social security numbers
• Credit card information
• Internal system IDs
• Private addresses

JWT tokens should contain only identity and authorization claims.

Privacy

Be mindful when displaying user information:

• Don't expose emails publicly
• Respect user privacy preferences
• Follow data protection regulations (GDPR, etc.)
• Only show necessary information

Integration Examples

React Component

function UserProfile() {
  const [profile, setProfile] = useState(null);

  useEffect(() => {
    client.readResource("user://profile").then(resource => {
      const data = JSON.parse(resource.contents[0].text);
      setProfile(data);
    });
  }, []);

  if (!profile) return <div>Loading...</div>;

  return (
    <div>
      <h1>{profile.name || profile.email}</h1>
      <p>User ID: {profile.userId}</p>
      {profile.metadata.groupCount > 0 && (
        <p>Groups: {profile.groups.join(", ")}</p>
      )}
    </div>
  );
}

Permission Guard

async function checkPermission(requiredGroup: string): Promise<boolean> {
  try {
    const resource = await client.readResource("user://profile");
    const profile = JSON.parse(resource.contents[0].text);
    return profile.groups?.includes(requiredGroup) ?? false;
  } catch {
    return false; // Not authenticated
  }
}

Cache Strategy

class UserProfileCache {
  private cache: any = null;
  private cacheTime: number = 0;
  private TTL = 5 * 60 * 1000; // 5 minutes

  async getProfile() {
    const now = Date.now();
    if (this.cache && now - this.cacheTime < this.TTL) {
      return this.cache;
    }

    const resource = await client.readResource("user://profile");
    this.cache = JSON.parse(resource.contents[0].text);
    this.cacheTime = now;
    return this.cache;
  }

  invalidate() {
    this.cache = null;
  }
}

Related Resources

• config://server - Server configuration and features

Related Tools

• user-info - Get user information as formatted text

Related Prompts

• user-context - Generate personalized messages using user data

Comparison: Resource vs Tool vs Prompt

user://profile (Resource)

• Returns structured JSON data
• For programmatic use
• Can subscribe to updates
• Read-only access

user-info (Tool)

• Returns formatted text
• For display to users
• One-time call
• Human-readable

user-context (Prompt)

• Generates personalized messages
• For conversational responses
• Template-based output
• Context-aware content

Choose based on your use case:

• Building UI → Use resource
• Showing info to user → Use tool
• Starting conversation → Use prompt

Next Steps

• All Resources - Return to resources overview
• config://server - Learn about server configuration resource
• Authentication Guide - Understand authentication flow
• Development Guide - Build custom resources