MCP Resources

Overview

MCP resources provide read-only access to data and configuration. Unlike tools (which perform actions) and prompts (which generate messages), resources expose structured data that clients can read and subscribe to for updates.

Resources are perfect for:

• Accessing configuration data
• Reading user profiles
• Getting reference information
• Subscribing to data changes
• Building reactive applications

Available Resources

config://server

Server configuration including enabled features, CORS settings, and logging configuration. Helps clients understand server capabilities.

Authentication Required: No

user://profile

Authenticated user's profile information from JWT token, including user ID, email, name, and group memberships.

Authentication Required: Yes

Quick Reference

Resource	URI	Auth Required	Purpose
config://server	config://server	No	Server configuration
user://profile	user://profile	Yes	User profile data

Using Resources with Claude

Reading Resources

Ask Claude to read a resource:

"Read the server configuration resource"
"Show me my user profile resource"
"What's in the config://server resource?"
"Get my profile from user://profile"

Claude will use the MCP protocol to read the resource and present the data.

Understanding URIs

Resources are identified by URIs with custom schemes:

• config:// - Configuration resources
• user:// - User-specific resources

The URI format is: scheme://path

Structured Data

Resources return structured data (typically JSON) rather than formatted text:

{
  "field1": "value1",
  "field2": 123,
  "nested": {
    "field3": true
  }
}

This makes resources ideal for programmatic use in applications.

Resource Operations

Reading

The primary operation is reading resource content:

{
  "method": "resources/read",
  "params": {
    "uri": "config://server"
  }
}

Subscribing

Clients can subscribe to resource updates:

{
  "method": "resources/subscribe",
  "params": {
    "uri": "config://server"
  }
}

When the resource changes, subscribers receive notifications:

{
  "method": "notifications/resources/updated",
  "params": {
    "uri": "config://server"
  }
}

Unsubscribing

Stop receiving updates:

{
  "method": "resources/unsubscribe",
  "params": {
    "uri": "config://server"
  }
}

Resource Response Format

Resources return content with metadata:

{
  "contents": [
    {
      "uri": "config://server",
      "mimeType": "application/json",
      "text": "{\"server\":{...},\"features\":{...}}"
    }
  ]
}

Response fields:

• uri: The resource identifier
• mimeType: Content type (usually application/json)
• text: The resource content as a string

Clients parse the text field to access the structured data.

Resource vs Tool vs Prompt

Use a Resource when:

• Accessing static or semi-static data
• Reading configuration or reference information
• Subscribing to data changes
• Building reactive features
• Need structured, programmatic data

Use a Tool when:

• Performing actions or operations
• Retrieving dynamic data
• Making calculations
• Interacting with external services
• Need operation results

Use a Prompt when:

• Generating conversational content
• Creating message templates
• Formatting data for presentation
• Starting conversations with context

Example Comparison

Getting User Information

Resource (user://profile):

{
  "userId": "user-123",
  "email": "dev@example.com",
  "name": "Jane",
  "groups": ["admin"]
}

→ Structured data for programmatic use

Tool (user-info):

**Authenticated User Information**
User ID: user-123
Email: dev@example.com
Name: Jane
Groups: admin

→ Formatted text for display

Prompt (user-context):

Welcome back, Jane!

Your email: dev@example.com
Your groups: admin

How can I assist you today?

→ Personalized message for conversation

Subscription Patterns

Reactive UI Updates

// Subscribe to user profile changes
await client.subscribe("user://profile");

// Listen for updates
client.on("notification", (notification) => {
  if (notification.method === "notifications/resources/updated" &&
      notification.params.uri === "user://profile") {
    // Re-read and update UI
    refreshUserProfile();
  }
});

Configuration Changes

// Subscribe to config changes
await client.subscribe("config://server");

// Adapt when config changes
client.on("notification", (notification) => {
  if (notification.params.uri === "config://server") {
    const newConfig = await readResource("config://server");
    applyNewConfig(newConfig);
  }
});

Authentication & Access

Public Resources

Resources like config://server are publicly accessible:

• No authentication required
• Available in all modes
• Safe to expose basic server information

Protected Resources

Resources like user://profile require authentication:

• Valid JWT token required
• Returns user-specific data
• Errors if not authenticated

Check the individual resource pages for authentication requirements.

Common Use Cases

Feature Detection

Read config://server
→ Check features.oauth
→ Show/hide OAuth button accordingly

User Personalization

Read user://profile
→ Get user.name
→ Display "Welcome, {name}!"

CORS Validation

Read config://server
→ Check cors.allowedOrigins
→ Verify current origin is allowed

Permission Checking

Read user://profile
→ Check user.groups
→ Show/hide features based on groups

Error Handling

Resources may return errors when:

• Authentication Required: Protected resource accessed without valid token
• Resource Not Found: URI doesn't match any available resource
• Server Error: Internal error reading resource data

Error responses include clear messages explaining the issue.

Best Practices

For Users

1. Check Authentication - Ensure you're authenticated for protected resources
2. Use Correct URIs - Resource URIs are case-sensitive
3. Handle Errors - Resources may fail, handle gracefully
4. Understand Data Structure - Each resource has its own schema

For Developers

1. Subscribe Wisely - Only subscribe to resources you need
2. Cache Appropriately - Resources are relatively static, can be cached
3. Unsubscribe When Done - Clean up subscriptions to save resources
4. Parse JSON Safely - Validate structure before accessing fields
5. Handle Optional Fields - Not all fields may be present

Resource Structure

MIME Types

Common resource MIME types:

• application/json - JSON data (most common)
• text/plain - Plain text
• text/markdown - Markdown content
• text/html - HTML content
• application/xml - XML data

Response Format

{
  "contents": [
    {
      "uri": "config://server",
      "mimeType": "application/json",
      "text": "{...json data...}"
    }
  ]
}

Security Considerations

What Resources Should Expose

✅ Safe to expose:

• Configuration options (feature flags, CORS settings)
• Public server information (name, version)
• User's own profile data
• Reference information

❌ Never expose:

• Secret keys or credentials
• Database passwords
• API keys
• Internal service URLs
• Other users' private data

Authentication

Protected resources must:

• Verify JWT token validity
• Check token expiration
• Validate user has permission to access the data
• Only return data the user is authorized to see

Next Steps

• config://server - Learn about server configuration resource
• user://profile - Learn about user profile resource
• MCP Tools - Explore available tools
• MCP Prompts - Learn about prompt templates
• Development Guide - Build custom resources