Parameterized resource templates in MCP servers

What a resource template advertises

A parameterized resource template is a server-advertised URI pattern for a family of MCP resources. It is useful when the exact members are not practical to list: the server publishes one construction rule instead of returning every possible concrete URI.

The MCP resources specification dated 2025-11-25 assigns templates their own discovery method, resources/templates/list. A response contains resourceTemplates, while resources/list returns individually identified resources. The distinction is structural: a listed resource has a concrete uri; a resource template has a uriTemplate containing variables.

A template advertises the address pattern, not the resources’ contents. It lets a client discover that a family exists and learn how to construct an address for one member. Retrieving that member remains a separate operation.

The URI template is a construction rule

MCP resource templates use the syntax defined by RFC 6570, published in March 2012. RFC 6570 describes a URI Template as a compact representation of a range of URIs. Expressions appear inside braces, and expansion replaces them using supplied variable values.

The MCP specification gives this example:

file:///{path}

Here, path is a variable rather than a concrete resource address. A conforming template processor parses the expression and expands it according to RFC 6570. The RFC defines more than simple replacement: operators control whether an expression produces a path component, query string, fragment, or another URI form, and its expansion rules determine how values are encoded. For example, {var} is a simple string expression, while {?q,lang} produces form-style query parameters from the defined variables.

That makes uriTemplate a machine-readable construction rule, not merely documentation containing braces. Implementations should use RFC 6570 expansion semantics rather than treating every expression as an unrestricted string substitution. If a template is relative, RFC 6570 says it is expanded before the resulting reference is resolved from relative to absolute form.

Template metadata is its own record

The MCP schema for protocol revision 2025-11-25 defines ResourceTemplate separately from Resource and from the text or binary content returned by a read. Its required fields are uriTemplate and name. It can also carry title, description, mimeType, icons, annotations, and _meta.

The specification’s example includes template-level metadata alongside the pattern:

{
  "uriTemplate": "file:///{path}",
  "name": "Project Files",
  "description": "Access files in the project directory",
  "mimeType": "application/octet-stream"
}

The template therefore has its own name, description, and MIME type metadata, separate from any resolved resource. name is required and intended for programmatic or logical use. An optional title provides a more human-readable label; when it is absent, clients can display name. The optional description explains what the template is for and can help a model understand the available resource family.

mimeType is also optional. The schema says it describes all resources matching the template and should appear only when every matching resource has the same type. A family that can resolve to several media types should omit it rather than publish a misleading common value.

This metadata describes the family before a member has been selected. A concrete Resource has its own uri and may have its own name, description, MIME type, annotations, and byte size. Resource contents returned by resources/read again identify the concrete URI and may state a MIME type alongside either text or a base64-encoded blob. Repeating MIME information at those levels does not merge the records: template metadata, resource metadata, and returned contents have different protocol roles.

Optional template icons and presentation fields belong to the same family-level record. Their display behavior and fallback rules are covered with the broader icons and presentation metadata used by MCP clients.

Discovery does not fill the variables

A client requests templates with resources/templates/list. The request supports pagination, and a response can include nextCursor when more templates may be available. Each returned entry tells the client which variables occur in the URI pattern, but the ResourceTemplate schema has no argument-schema field declaring variable types, required values, or enums.

The client therefore needs user or model input before it can read a member of the family. The MCP specification does not require one interface for obtaining that input. A host might present a field or picker to the user, let a model select values, or combine the two. The specification also permits template arguments to be auto-completed through MCP’s completion API, but completion assistance does not remove the need to choose concrete values.

The protocol flow is:

resources/templates/list
        ↓
URI template plus template metadata
        ↓
user or model supplies variable values
        ↓
RFC 6570 expansion produces a concrete URI
        ↓
resources/read receives that concrete URI

This is client-side binding from a protocol perspective. There is no separate “execute resource template” request carrying a template identifier and a map of arguments. The value crossing the resources/read boundary is the expanded URI.

Reading the resolved resource

After expansion, the client sends resources/read with the concrete URI in params.uri. The request schema contains the URI, plus optional request metadata; it does not contain uriTemplate or a variable map. The server responds with one or more text or binary content records associated with concrete URIs.

A placeholder-bearing template is therefore not a substitute for the read address. Discovery returns the family description; input selects a member; expansion constructs its address; resources/read asks the server for that address. The broader sequence for fixed and parameterized resources is covered in discovering and reading MCP resources.

Template expansion does not bypass server checks. The resources specification requires servers to validate resource URIs, recommends access controls for sensitive resources, and says resource permissions should be checked before operations. It also defines JSON-RPC error -32002 for a resource that is not found. A syntactically expanded URI can consequently still produce a normal read error.

Scope and nearby protocol concepts

Resource templates belong to the server’s resources surface, so the server declares the resources capability during initialization. The optional subscribe and listChanged flags describe update features; neither changes how template variables are expanded. The surrounding initialization contract is explained in MCP capability negotiation.

Resource templates should not be confused with server-provided prompt templates. A resource template constructs a URI and ends in resources/read. A prompt definition advertises named arguments and is resolved through prompts/get. The next details to check for a resource implementation are its RFC 6570 expression semantics, how the client obtains or completes variable values, what family-level metadata is accurate, and how the server validates the resulting concrete URI.