Correct usage of resources read returning multiple contents

[vinsguru]

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

Your Question

I am implementing an MCP server and I want to confirm that I am using the Resources API as intended by the specification.

The product domain used in this example is purely hypothetical and is only meant to illustrate the usage pattern. The number of contents returned is intentionally small, with a maximum of ten items, so response size is not a concern.

In my server, a resource URI such as product://summer-specials represents a collection of items. When the client performs a resources/read request for this URI, the server returns multiple ResourceContents, where each content has its own URI and represents an individual item.

For example, reading product://summer-specials returns contents such as product://1, product://2, and product://3, each with its own text payload.

// MCP read resource request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "product://summer-specials"
  }
}

// MCP read resource result
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "contents": [
      {
        "uri": "product://1",
        "mimeType": "text/plain",
        "text": "iphone"
      },
      {
        "uri": "product://2",
        "mimeType": "text/plain",
        "text": "ipad"
      },
      {
        "uri": "product://3",
        "mimeType": "text/plain",
        "text": "macbook"
      }          
    ]
  }
}

My question is whether this response structure aligns with the intended MCP usage, where a single resource read can resolve into multiple resource contents with different URIs, effectively modeling a collection or index resource.

[olaservo]

Hi @vinsguru, yes, this is a valid and intentional pattern in MCP.

The spec explicitly supports this through several design choices:

1. ReadResourceResult.contents is an array - The schema deliberately returns an array of ResourceContents, not a single item.
2. The spec acknowledges "sub-resources" - The ResourceContents type is documented as representing "the contents of a specific resource or sub-resource" (see the https://modelcontextprotocol.io/specification/2025-11-25/schema).
3. Subscription semantics confirm this - The ResourceUpdatedNotification explicitly states the URI "might be a sub-resource of the one that the client actually subscribed to."

Your example pattern is exactly what this design enables:

// Request: resources/read for "product://summer-specials"
// Response:
{
  "contents": [
    { "uri": "product://1", "text": "{\"name\": \"Summer Hat\", ...}" },
    { "uri": "product://2", "text": "{\"name\": \"Beach Towel\", ...}" },
    { "uri": "product://3", "text": "{\"name\": \"Sunglasses\", ...}" }
  ]
}

This can be useful for modeling collections, indexes, or composite resources where reading a parent URI naturally expands into its constituent items.

I added a comment to the new 'everything demo' reference implementation that Cliff is working on here to consider adding an example of this too.

---

(originally written by Claude and edited by me)

[vinsguru]

I appreciate you taking the time to review the example and for adding a note to the reference implementation to consider including this pattern. It will be very helpful for others trying to understand how collections and index-style resources can be modeled in MCP.

Thanks again for the guidance. 🙏