MCP Resource Templates

An MCP resource template is a pattern for a family of resources, written as a URI template like file:///{path}. Instead of listing every file or record one by one, a server publishes the pattern. The client fills in the variables to build a concrete URI, then reads it with resources/read.

Status in the 2026-07-28 spec: core. Templates are part of the Resources feature and have existed since the first dated spec, 2024-11-05.

Templates solve a scale problem. A server with a million customer records cannot list them all, but it can publish one template. This page is based on the 2026-07-28 Resources page and schema, checked on 28 October 2026.

What a resource template is

RFC 6570 defines a URI template as a compact string that describes a range of URIs by substituting variables. For example, {var} with var set to "value" expands to value.

MCP uses that standard. The spec says resource templates "allow servers to expose parameterized resources using URI templates." The schema defines uriTemplate as "a URI template (according to RFC 6570) that can be used to construct resource URIs."

A template definition includes:

The mimeType rule is worth noting. The schema says to include it "only if all resources matching this template have the same type."

Why templates exist

A plain resources/list works for a handful of fixed items. It breaks down for large or open-ended data, like every file in a repository or every order in a store.

Templates let a server say "you can read any order by ID" in one entry. The host app can then build a form, a search box or an auto-complete field around the variables. That fits the application-driven model for resources.

How it works

Listing templates

The client sends resources/templates/list. Here is a response adapted from the spec example (icons removed):

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resultType": "complete",
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "title": "Project Files",
        "description": "Access files in the project directory",
        "mimeType": "application/octet-stream"
      }
    ],
    "nextCursor": "next-page-cursor",
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

The 2026-07-28 page says this operation supports pagination and caching. The ttlMs and cacheScope fields are required on resources/templates/list results, per the 2026-07-28 changelog.

Filling in the variables

The client, often with the user's help, fills the variables. For file:///{path}, the path src/main.rs gives file:///src/main.rs. The client then sends a normal resources/read with that URI.

Auto-completing arguments

The spec says template arguments "may be auto-completed through the completion API." The client sends completion/complete with a reference of type ref/resource and the template URI. The server returns up to 100 suggestions. Our guide to MCP argument completion covers the details.

An illustrative example, using the spec's reference format:

{
  "method": "completion/complete",
  "params": {
    "ref": { "type": "ref/resource", "uri": "file:///{path}" },
    "argument": { "name": "path", "value": "src/ma" }
  }
}

What changed across spec versions

The core idea has not changed since 2024. Most changes added display metadata or followed protocol-wide updates like caching and the stateless design described in why MCP became stateless.

Common mistakes

1. Trusting the expanded URI. A template is a hint, not a filter. Users or models can send any URI to resources/read. The spec says servers MUST validate all resource URIs and sanitize file paths to prevent directory traversal.
2. Setting mimeType on a mixed template. If a template can return both images and text, leave mimeType off.
3. Expecting templates in resources/list. Templates come from their own method, resources/templates/list.
4. No completion support for big value sets. If users must guess IDs, the template is hard to use. Declare the completions capability and suggest values.
5. Leaking data through completion. The completion spec says implementations must control access to sensitive suggestions. Do not suggest record IDs the caller cannot read.

Read the MCP security center for more on path traversal and access control. Our Learn MCP lesson on adding resources shows templates in code.

Next step

Once a client reads a resource, it may want to know when it changes. Read MCP resource subscriptions next, or return to the MCP specification reference.

Frequently asked questions