What is an MCP resource template, and when do you publish one instead of a resource?

## The problem templates solve `resources/list` returns a finite array of descriptors. That is fine for a server exposing a dozen configuration documents and hopeless for one exposing every file in a monorepo, every ticket in a tracker, or every row in a table. Enumerating those is either impossibly large, impossibly slow, or both — and the listing would be stale by the time the client used it. A **resource template** describes the *shape* of an address instead of listing every address. The server says "anything matching this pattern is readable", and the client constructs the specific URI it wants. ## resources/templates/list Templates are published by their own method, `resources/templates/list`, which returns a `resourceTemplates` array. Each entry looks like a resource descriptor with one substitution: instead of a fixed `uri`, it carries a `uriTemplate`. The other fields are the same — `name`, optional `description`, optional `mimeType` — and serve the same purpose: telling a human or a model what this family of resources is and what reading one will produce. Keeping templates on a separate method matters. A client that only understands concrete resources can call `resources/list` and ignore templates entirely; nothing in a listing is ever unexpandable. ## RFC 6570 syntax `uriTemplate` is an **RFC 6570 URI Template**. The basics: `{var}` is a simple variable expansion that percent-encodes reserved characters, so `db://orders/{orderId}` with `orderId=42` becomes `db://orders/42`. The `+` operator, as in `{+path}`, is reserved expansion — it allows `/` and other reserved characters through unencoded, which is exactly what you want for a path variable like `git://repo/{+path}` expanding to `git://repo/src/main/App.kt`. That distinction is the one to get right. Using `{path}` for a multi-segment path percent-encodes the slashes into `%2F`, producing a URI the server will not recognise. Using `{+path}` where you meant a single opaque segment lets a value smuggle extra path structure into the URI, which is why a server must still validate what it receives rather than trusting that expansion preserved its intent. ## Reading a template There is no "read a template" call. The client expands the template into a concrete URI and calls `resources/read` with that URI as normal. Everything else follows the ordinary resource rules: the result is a `contents` array of text or blob entries with a required `resultType`, and a missing target is an error rather than an empty result. This is also why a template's variables must be things the client can plausibly know. A template whose variable is an internal surrogate key nobody can guess is a template nobody can use. ## Helping the client fill the variables Since the client supplies the values, servers can support argument completion through `completion/complete` with a `ref/resource` reference naming the template. The host then offers suggestions as the user types a path or an id, turning an unguessable space into a browsable one. It is optional, but a template without completion often means the user must already know the exact identifier. ## Templates and concrete resources together The two are not exclusive, and good servers publish both. List the small set worth surfacing in a picker — the README, the current config, today's log — and template the long tail so anything else remains reachable. The revision 2026-07-28 rule that the resource set MUST NOT vary per connection applies to templates as well: they may differ by the authorization presented, but not because of what happened earlier on the same connection, since MCP is stateless and an open stdio process is not a session. ## Where templates end and tools begin A template is still an *address*. If reaching the data needs several independent parameters, a query, ranking, or anything with a side effect, that is not addressing any more and belongs behind a tool. A URI template with six variables encoding a search query is a tool wearing a costume. The honest test: could a user bookmark the expanded URI and get the same content back later? If yes, it is a resource; if not, it is an operation. ## Common mistakes Calling `resources/read` with an unexpanded template string; using `{var}` where `{+var}` is needed for paths; publishing templates whose variables nobody can supply; and assuming `resources/list` will also return the templates — it will not, they have their own method.