MCP · Building servers and clients · all subjects

primitives: resources

31 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Resources are identified by URI and declare a MIME type

Each resource has a unique URI (for example `file:///path/to/document.md`) and declares its MIME type so content is handled appropriately. Resources can expose data from files, APIs, databases, or any other source.

Direct resources vs resource templates

Resources support two discovery patterns. Direct Resources use fixed URIs pointing to specific data, e.g. `calendar://events/2024`. Resource Templates use dynamic URIs with parameters, e.g. `travel://activities/{city}/{category}` expanded to `travel://activities/barcelona/museums`. Resource Templates include metadata such as title, description and expected MIME type so they are discoverable and self-documenting.

Resource protocol methods: list, templates/list, read, subscriptions/listen

Resource protocol operations are: `resources/list` (list available direct resources, returns array of resource descriptors), `resources/templates/list` (discover resource templates, returns array of resource template definitions), `resources/read` (retrieve resource contents, returns resource data with metadata), and `subscriptions/listen` (monitor resource changes, returns a stream of update notifications).

Subscribing to resource updates via resourceSubscriptions filter

To watch specific resources for changes, the client sends a `subscriptions/listen` request with the resource URIs listed in the `resourceSubscriptions` filter. The server then delivers `notifications/resources/updated` on the resulting stream whenever a watched resource changes.

Resource template JSON example

A resource template is declared as JSON with `uriTemplate`, `name`, `title`, `description` and `mimeType`, for example: { "uriTemplate": "weather://forecast/{city}/{date}", "name": "weather-forecast", "title": "Weather Forecast", "description": "Get weather forecast for any city and date", "mimeType": "application/json" } and { "uriTemplate": "travel://flights/{origin}/{destination}", "name": "flight-search", "title": "Flight Search", "description": "Search available flights between cities", "mimeType": "application/json" }.

Parameter completion for resource templates and prompt arguments

Dynamic resources support parameter completion so users discover valid values without knowing exact formats: typing "Par" for `weather://forecast/{city}` might suggest "Paris" or "Park City", and typing "JFK" for `flights://search/{airport}` might suggest "JFK - John F. Kennedy International". Prompts similarly support parameter completion for argument values.

Application decides how resource content reaches the model

The AI application retrieves resources and decides how to process them — selecting a subset with embeddings or keyword search, or passing raw data directly to the model. Servers should therefore return resource content that is useful when only partially consumed rather than assuming the whole payload reaches the model.

Legacy resource subscriptions: resources/subscribe

In the legacy era, subscribing to a resource sends `resources/subscribe`; when the resource changes the server emits `notifications/resources/updated`. It is a session flag rather than a stream.

Modern resource subscriptions: subscriptions/listen stream

In the modern era, subscribing sends `subscriptions/listen` with a filter carrying `resourceSubscriptions` plus a `resourcesListChanged` opt-in. The subscription is confirmed when the server sends `notifications/subscriptions/acknowledged`. It is a long-lived stream, so if the stream drops the client should reconnect by re-sending `subscriptions/listen`.

App metadata (csp, permissions, domain) lives on the UI resource, not the tool

For MCP Apps, the `csp` and `permissions` fields (and `domain`, when the resource declares one) are declared on the UI **resource** rather than on the tool, so `--app-info` reads that resource. A sample `--app-info` payload is: {"hasApp": true, "toolName": "get_pros", "resourceUri": "ui://pros/view.html", "csp": {"connectDomains": ["https://api.example.com"]}, "permissions": {"clipboard": false}, "prefersBorder": true, "resourceMimeType": "text/html"}.

ui:// URI scheme for MCP App resources

MCP App UI resources use the `ui://` URI scheme, which tells hosts the resource is an MCP App UI (for example `ui://get-time/mcp-app.html`). The path structure after the scheme is arbitrary and can be organized however you want.

ui:// resource contains bundled HTML/JS/CSS

After a tool declares a UI resource, the host fetches the UI resource from the server. That resource contains an HTML page, usually bundled with its JavaScript and CSS for simplicity. Apps can also load external scripts and resources from origins listed in `_meta.ui.csp`.

_meta.ui object fields: csp and permissions

A UI resource's `_meta.ui` object can include `permissions` to request additional capabilities such as microphone or camera, and `csp` to control which external origins the app may load resources from. Web hosts typically render the HTML in a sandboxed iframe inside the conversation.

Inspector Resources tab: templates, MIME types, subscribe

The Inspector Resources tab lists resources and resource templates with their MIME types and descriptions, reads content on selection, and offers a Subscribe control on servers that support subscriptions. Subscription mechanics differ between the legacy and modern protocol eras.

How to expose a resource and how clients read it

Servers expose resources through the resources capability and must respond to resources/list requests to provide the set of available resources. Clients discover resources by sending a resources/list request with optional pagination cursor. To read a resource, clients send a resources/read request with the resource URI. The server responds with the resource contents, which can be text or binary data. Servers may return multiple resource contents in a single resources/read response, and resources may also respond with InputRequiredResult to indicate additional input is needed before the resource can be read, following the multi round-trip requests mechanism.

Resources capability declaration with listChanged and subscribe

Servers that support resources must declare the resources capability in their response. The capability supports two optional features: listChanged (whether the server will emit notifications when the list of available resources changes) and subscribe (whether the server supports resource-specific update notifications for resources requested through subscriptions/listen using the resourceSubscriptions filter). Servers may advertise either feature independently, together, or neither. If a server supports neither listChanged nor subscribe, it may omit them and just declare an empty resources capability object.

Resources list request and response structure

The resources/list request has a params object with an optional cursor field for pagination. The response contains resultType ("complete"), a resources array, an optional nextCursor field for pagination, ttlMs (time-to-live in milliseconds for caching), and cacheScope ("public" or "private"). Each resource object includes: uri (unique identifier), name, optional title, optional description, optional mimeType, and optional icons array where each icon has src, mimeType, and sizes fields.

Resources read request and response structure

The resources/read request has a params object with a required uri field identifying the resource to read. The response contains resultType ("complete"), a contents array of resource content objects, ttlMs for caching, and cacheScope. Each content object includes uri, mimeType, and either a text field (for text content) or a blob field (for base64-encoded binary data).

Resource templates with URI templates

Resource templates allow servers to expose parameterized resources using URI templates as defined in RFC 6570. Clients list resource templates by sending a resources/templates/list request with optional pagination cursor. The response includes resultType, resourceTemplates array, optional nextCursor, ttlMs, and cacheScope. Each resourceTemplate object includes uriTemplate, name, optional title, optional description, optional mimeType, and optional icons. Arguments in resource templates may be auto-completed through the completion API.

List changed notification for resource updates

When the list of available resources changes, servers that declared the listChanged capability should send a notifications/resources/list_changed notification. This notification is a JSON-RPC notification with jsonrpc "2.0" and method "notifications/resources/list_changed", with no params required.

Resource subscriptions for change notifications

Clients can subscribe to change notifications for specific resources by sending a subscriptions/listen request with resource URIs listed in the notifications.resourceSubscriptions filter. The server delivers notifications/resources/updated on the resulting stream whenever a watched resource changes. Each notification includes the resource uri and has a _meta field containing io.modelcontextprotocol/subscriptionId for correlation.

Resource annotations: audience, priority, lastModified

Resources, resource templates, and content blocks support optional annotations that provide hints to clients. The annotations object can contain: audience (array of "user" and/or "assistant" indicating intended audience), priority (number from 0.0 to 1.0 where 1 means most important and 0 means least important), and lastModified (ISO 8601 formatted timestamp like "2025-01-12T15:00:58Z"). Clients can use these annotations to filter resources, prioritize which to include in context, and display modification times.

Resource data type fields: uri, name, title, description, mimeType, size, icons

A resource definition includes: uri (unique identifier for the resource, required), name (the name of the resource, required), title (optional human-readable name for display purposes), description (optional description), mimeType (optional MIME type), size (optional size in bytes), and icons (optional array of icons where each icon has src, mimeType, and sizes fields).

Resource text and binary content encoding

Resources can contain either text or binary data. Text content is provided in a text field as a string. Binary content is provided in a blob field as base64-encoded data. Each content block includes the resource uri, mimeType, and either the text or blob field depending on the content type.

HTTPS URI scheme for web-accessible resources

The https:// URI scheme is used to represent a resource available on the web. Servers should use this scheme only when the client is able to fetch and load the resource directly from the web on its own without needing to read the resource via the MCP server. For other use cases, servers should prefer to use another URI scheme or define a custom one, even if the server will itself be downloading resource contents over the internet.

File URI scheme for filesystem-like resources

The file:// URI scheme is used to identify resources that behave like a filesystem. However, the resources do not need to map to an actual physical filesystem. MCP servers may identify file:// resources with an XDG MIME type, like inode/directory, to represent non-regular files (such as directories) that don't otherwise have a standard MIME type.

Git URI scheme for version control

The git:// URI scheme is used for Git version control integration.

Custom URI schemes must comply with RFC 3986

Custom URI schemes must be in accordance with RFC 3986.

Resources list must not vary per-connection or by other request side effects

Servers that declare the resources capability must respond to resources/list requests with the set of resources currently available to the requesting client. This set may be empty and may change over time, but must not vary per-connection or as a side effect of other requests on the connection. The set may vary by the authorization presented on the request (for example, returning only the resources the caller's granted scopes permit), since credentials are per-request input, not connection state.

Resources operations support pagination and caching

The resources/list operation and resources/templates/list operation both support pagination and caching. The resources/read operation supports caching. Pagination is provided through cursor fields, and caching is controlled through ttlMs (time-to-live in milliseconds) and cacheScope fields in responses.

MCP Registry launched

The MCP Registry preview was launched in September 2025 as an open catalog and API for indexing and discovery of MCP servers. It serves as the single source of truth for available MCP servers, supporting both public and private sub-registries. Any MCP client can consume registry content via the native API or through third-party registry aggregators.

Give your agent this brain