Skip to content

CONCEPT Cited by 1 source

URI template (RFC 6570)

Definition

A URI template per RFC 6570 is a URI pattern with {placeholder} expressions that expand into concrete URIs at request time. Template expansion fills the placeholders with caller-supplied values; template matching (the inverse direction) extracts values from a concrete URI back into a variable map. The spec is the workhorse used by GitHub's API discovery, OpenAPI path parameters, HAL hypermedia, and — as of the 2026-01-08 Wix tutorial canonicalised on this wiki — parameterised MCP resources (Source: sources/2026-01-08-wix-mcp-resources-all-you-need-to-know).

Syntax shapes

/users/{userId}                    # path parameter, Level 1
/search{?q,lang}                   # query parameters, Level 3
/users/{userId}/posts/{postId}     # multiple path params
/files{/path*}                     # path exploder, Level 3

RFC 6570 defines four levels of template expressiveness — most real-world use is at Levels 1-3.

Use in MCP

MCP template resources use URI templates to parameterise a single resource registration so one handler can serve many concrete resources. Example from Wix:

const uri = 'resource://user-profile/{userId}';

const resourceTemplate = new ResourceTemplate(
    uri,
    { list: undefined },   // optional listing callback
);

server.registerResource(
    'user-profile',
    resourceTemplate,
    { description, mimeType: 'application/json' },
    async (uri, variables) => {
      const rawUserId = variables.userId;
      const userId = Array.isArray(rawUserId) ? rawUserId[0] : rawUserId;
      if (!userId) throw new Error('userId parameter is required');
      const userData = await fetchUserData(userId);
      return {
        contents: [{
          mimeType: 'application/json',
          uri: uri.toString(),
          text: JSON.stringify(userData, null, 2),
        }],
      };
    },
);

Two production rules canonicalised by the Wix tutorial:

  • Prefer path parameters to query parameters for MCP resources. Verbatim: "According to URI template specification you can use both path parameters like resource://user-profile/{userId} and query parameter like resource://user-profile?userId={userId}. However, not all clients understand query parameters so try to avoid them."
  • Handle both single-valued and multi-valued variables in the handler. Per spec, "one variable might have more than one value" — the handler's variables.userId can be either a string or a string[]. Defensive code: const userId = Array.isArray(rawUserId) ? rawUserId[0] : rawUserId;.

Companion: RFC 3986

RFC 6570 templates expand into URIs valid per RFC 3986 (the generic URI syntax). When picking the scheme portion of an MCP resource URI, the JavaScript URL constructor used by @modelcontextprotocol/sdk has custom handling for certain schemes that breaks resource resolution — see concepts/mcp-resource for the file:// trailing-slash gotcha. Custom schemes (doc://, log://, git://, resource://) sidestep the issue.

Seen in

Last updated · 476 distilled / 1,218 read