MCP Resources and URI Templates
Learn how to document MCP resources: concrete URIs, URI templates with parameters, content types, subscriptions, audience control, and metadata. Understand the difference between tools and resources and when to use each.
Resources expose data to AI assistants without requiring tool invocations. Unlike tools (which are model-controlled), resources are application-controlled: the host application decides which resources to make available in the current context. This makes resources ideal for providing background data, reference material, and live system state.
Tools versus Resources
Understanding when to use a tool versus a resource is essential for effective MCP server design.
| Aspect | Tools | Resources |
|---|---|---|
| Control | Model-controlled (LLM decides) | Application-controlled (host decides) |
| Direction | Invoke an action | Read data |
| Side effects | May modify state | Read-only by nature |
| Parameters | Input schema (JSON Schema) | URI or URI template parameters |
| Use when | The AI needs to perform an action | The AI needs to browse or read data |
| Example | search_products(query, maxPrice) | ecommerce://catalogue/electronics |
Concrete URIs
A concrete resource has a fixed URI that always returns the same type of data. Use concrete URIs for static or slowly-changing data like configuration files, policy documents, and system metadata.
{
"name": "return-policy",
"uri": "ecommerce://policies/returns",
"isTemplate": false,
"mimeType": "text/markdown",
"contentType": "text"
}URI Templates
Templated resources use parameterised URIs that resolve to different data based on the parameters provided. NeoArc highlights template parameters with accent colouring in the published viewer.
{
"name": "product-catalogue",
"uri": "ecommerce://catalogue/{category}",
"isTemplate": true,
"templateParameters": [
{
"name": "category",
"description": "Product category slug",
"required": true,
"examples": ["electronics", "clothing", "all"]
}
]
}Content Type and MIME Type
Resources declare their content format so clients know how to process the data.
| Field | Values | Purpose |
|---|---|---|
| contentType | text, blob | Whether the content is text-based (can be displayed) or binary (needs special handling) |
| mimeType | application/json, text/markdown, etc. | The specific media type for content negotiation and rendering |
Subscriptions
Resources can be marked as subscribable, enabling real-time notifications when the underlying data changes. When a client subscribes to a resource, the server sends notifications whenever the resource content is updated.
Document the subscription behaviour clearly: how frequently updates occur, what triggers a notification, and whether the notification contains the full content or just a change indicator.
Audience Control
Each resource can specify its intended audience using two flags.
Metadata
Resources can include metadata that helps clients manage their resource loading.
| Field | Purpose | Example |
|---|---|---|
| estimatedSize | Hint about content size for bandwidth planning | ~50KB, ~2MB |
| priority | Relative importance (0.0 to 1.0) for loading order | 0.9 for critical context, 0.3 for supplementary |
Examples
Resource examples show concrete URI instances with content previews. For templated resources, examples demonstrate different parameter combinations and the resulting data.
Related Guides
Deep dive into MCP tool definitions: annotation flags, safety matrix, input/output schemas, error scenarios, result content types, related resources, and example patterns. Learn how to document tools that AI assistants can use safely and effectively.
Document MCP prompt templates: typed arguments with completion support, expected message flows with role and content type, worked examples with argument-to-output mappings, and prompt engineering patterns for consistent AI behaviour.