Whatever message this page gives is out now! Go check it out!
Read Handlers and MIME Types
Last update:
May 18, 2026
Behind every resource URI, your MCP server needs a read handler that retrieves and formats data, along with an accurate MIME type describing the data format.
Overview
Behind every resource URI, your MCP server needs a read handler: a piece of logic that knows how to retrieve and format the data for that URI.
What Is a Read Handler?
A read handler:
- Accepts a URI (
file:///var/log/app.log,reports://sales/2025-02-01, etc.). - Fetches the relevant data from the appropriate backend:
- File system
- Database
- External API
- In-memory cache or computed result
- Returns a content block with:
- The same
uri - A
mimeType - The content itself as text or bytes (or another supported form)
- The same
From your standpoint, read handlers are what make URIs meaningful. You don’t call them directly; you just issue
resources/read on a URI, and the server’s handler does the rest. MIME Types: Describing the Data Format
Every resource should declare a MIME type (a standard descriptor of data format), such as:
text/plain– plain text logs, notes, or configsapplication/json– JSON objects, reports, or structured datasetstext/markdown– markdown documentstext/html– HTML pages or fragmentsapplication/pdf– PDF documents (if supported by your tools)
Why it matters:
- The agent can decide how to handle the content:
- Parse JSON when
application/json - Treat it as free-form text when
text/plain - Apply specialized tools for PDFs, HTML, etc.
- Parse JSON when
- UI and tooling can offer richer views (syntax highlighting, viewers, etc.).
- Downstream tools can validate that they’re being fed the expected type.
As a user, you can expect the MCP server to:
- Provide accurate MIME types so tools behave correctly.
- Avoid lying about type (e.g., calling JSON “text/plain” when it isn’t).
Reading a Resource: What You Get Back
A typical
resources/read result might look like:
{
"contents": [
{
"uri": "logs://app/today",
"mimeType": "text/plain",
"text": "2026-03-01 10:00:01 ERROR ...\n2026-03-01 10:03:15 WARN ...\n..."
}
]
}
or for JSON:
{
"contents": [
{
"uri": "reports://sales/2025-02-01",
"mimeType": "application/json",
"text": "{ \"date\": \"2025-02-01\", \"total\": 123456, \"regions\": [...] }"
}
]
}
Some implementations may include a
json field instead of raw text when convenient, but the MIME type remains your primary hint about how the contents should be interpreted. How This Affects Your Workflows
As a user:
- You ask the agent to read specific URIs or to choose from
resources/list. - The agent calls
resources/read, then:- Parses the content based on
mimeType. - Summarizes, analyzes, or passes it into other tools.
- Parses the content based on
You don’t need to know whether:
- The log is on disk or in cloud storage.
- The report is pre-generated or computed on the fly.
- The customer profile comes from a database or an API.
The MCP abstraction hides those details behind read handlers and MIME types, giving you a consistent way to say:
“Read this resource and help me understand it.”
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
