Read Resource

​

Overview

The resources/read method retrieves the content of a specific resource by its URI. Resources can contain text data, binary data (base64-encoded), or structured information depending on their MIME type.

​

Prerequisites

1. Session Initialization: Complete initialize → notifications/initialized flow
2. Authentication: Valid OAuth token or PAT with mcp.read scope
3. Session ID: Include Mcp-Session-Id header from initialization
4. Resource Discovery: Use resources/list to discover available resource URIs

​

Request Format

{
  "jsonrpc": "2.0",
  "id": "resources-read-123",
  "method": "resources/read",
  "params": {
    "uri": "pipedrive://deals/12345"
  }
}

​

Request Parameters

​

Response Format

​

Example Responses

{
  "jsonrpc": "2.0",
  "id": "resources-read-123",
  "result": {
    "contents": [
      {
        "uri": "pipedrive://deals/12345",
        "text": "{\n  \"id\": 12345,\n  \"title\": \"Acme Corp Integration Project\",\n  \"value\": 50000,\n  \"currency\": \"USD\",\n  \"stage\": \"Negotiation\",\n  \"probability\": 75,\n  \"expected_close_date\": \"2024-02-15\",\n  \"person\": {\n    \"id\": 67890,\n    \"name\": \"John Doe\",\n    \"email\": \"john@acmecorp.com\"\n  },\n  \"activities\": [\n    {\n      \"type\": \"call\",\n      \"date\": \"2024-01-10\",\n      \"subject\": \"Technical requirements discussion\"\n    },\n    {\n      \"type\": \"email\",\n      \"date\": \"2024-01-12\",\n      \"subject\": \"Proposal follow-up\"\n    }\n  ]\n}",
        "mimeType": "application/json"
      }
    ]
  }
}

​

Content Types and Encoding

​

Text Content

Text-based resources return content in the text field:

• JSON Data: Structured CRM data (deals, contacts, activities)
• Plain Text: Notes, descriptions, logs
• CSV Data: Exported data tables
• HTML: Formatted content

​

Binary Content

Binary resources return base64-encoded data in the blob field:

• PDF Documents: Proposals, contracts, reports
• Images: Screenshots, diagrams, photos
• Archives: ZIP files, compressed data
• Other Files: Any binary file type

​

Content Validation

Each content item must have either text or blob, but not both:

// Valid text content
{
  "uri": "pipedrive://deals/123",
  "text": "{\"id\": 123, \"title\": \"Deal\"}",
  "mimeType": "application/json"
}

// Valid blob content
{
  "uri": "pipedrive://files/doc.pdf",
  "blob": "JVBERi0xLjQK...",
  "mimeType": "application/pdf"
}

// Invalid - cannot have both text and blob
{
  "uri": "pipedrive://invalid",
  "text": "some text",
  "blob": "some blob"  // ERROR: Cannot have both
}

​

URI Validation and Access Control

​

URI Format Validation

Resource URIs must:

• Follow valid URI syntax with scheme and path
• Use supported schemes (pipedrive://)
• Reference existing resources in the user’s data scope
• Contain valid identifiers and paths

​

Permission Checking

Access is controlled at multiple levels:

1. OAuth Token: Valid token with mcp.read scope
2. Session: Active session with proper authentication
3. Resource Permission: User must have access to specific resource
4. Data Ownership: Resource must be accessible to user’s client_id

​

Error Conditions

​

Implementation Notes

​

Request ID Requirements

• Must be unique within session
• Cannot be null (enforced by implementation)
• Used for error correlation and response tracking

​

Session Validation

• Mcp-Session-Id header required after initialization
• Session must be active and authenticated
• Invalid session returns authentication error

​

Content Processing

• Text content returned as-is (no additional encoding)
• Binary content base64-encoded for JSON transport
• MIME types accurately reflect actual content
• Large files may be chunked or compressed

​

Performance Considerations

• Resource content cached where appropriate
• Large binary files may have size limits
• Database queries optimized for resource retrieval
• Binary encoding adds ~33% overhead to file size

​

Error Handling

• -32000: Authentication/session errors
• -32001: Resource not found or access denied
• -32602: Invalid URI parameter
• -32603: Internal server error

​

Content Size Limits

• Text content: Generally no strict limit
• Binary content: May have size restrictions for performance
• Base64 encoding increases binary file size by ~33%
• Large files may require alternative access methods

​

MIME Type Detection

• MIME types automatically detected from content
• Override capability for specific resource types
• Standard MIME types used for consistency
• Custom types supported for specialized content

This method provides access to the actual resource content, enabling language models to process CRM data, documents, and other contextual information for analysis and interaction.