Resources

Resources are the data primitive: read-only values the client fetches by URI. Where a tool runs code and a prompt seeds a conversation, a resource answers a read — the client asks for a URI and your handler returns what lives there. A resource is addressed rather than called, which is why it carries a URI instead of an input schema, and why a single registration can serve either one fixed address or a whole family of them through a template.

Registration

You register a resource with server.resource(config, handler) — the same config-first shape as every other primitive. FastMCP decides whether you’ve registered a static resource or a template by looking for a { in the URI string, so there is no separate method to learn. A plain URI is a static resource; a URI with a {param} placeholder is a template, and the extracted parameters are passed to your handler as an object.

server.ts

import { FastMCP } from '@prefecthq/fastmcp-ts/server'

const server = new FastMCP({ name: 'my-server' })

// Static resource — one fixed address
server.resource(
  { uri: 'config://settings', description: 'App configuration' },
  () => JSON.stringify({ theme: 'dark', lang: 'en' }),
)

// Template — one registration serves every matching URI
server.resource(
  { uri: 'user://{id}', description: 'User by ID' },
  ({ id }) => `User #${id}`,
)

The two kinds surface differently to clients. Static resources appear in resources/list and are fetched with resources/read. Templates appear in resources/templates/list so a client knows the address shape it can fill in, and each concrete read is matched back to your template at request time using RFC 6570 extraction.

URI templates

A template lets one handler serve an open-ended set of addresses, and the placeholder style controls how much of the URI each parameter captures. The default captures a single path segment, which suits identifiers; a wildcard captures many segments, which suits file paths; and a query style captures query-string parameters, which suits search and filtering. Choose the style that matches the shape of the data you’re addressing.

Style	Example	Captures
Simple	`user://{id}`	A single path segment
Wildcard	`files://{path*}`	Multiple path segments
Query	`search://items{?q,lang}`	Query-string parameters

server.ts

// Wildcard — {path*} captures "docs/guide/intro.md" whole
server.resource(
  { uri: 'files://{path*}', description: 'Read a file by path' },
  ({ path }) => readFileSync(path, 'utf8'),
)

// Query — {?q,lang} captures ?q=mcp&lang=en
server.resource(
  { uri: 'search://items{?q,lang}', description: 'Search items' },
  ({ q, lang }) => runSearch(q, lang ?? 'en'),
)

Return values

Your handler returns a plain value and FastMCP converts it into an MCP ReadResourceResult. The conversion mirrors the tool conversion but is tuned for data: strings become text, raw bytes become a base64 blob, and structured values become JSON. The MIME type is inferred from the return type, and you override it with the mimeType config field when the default is wrong.

Returned value	Conversion
`string`	Text content (`mimeType` defaults to `text/plain`)
`Buffer` / `Uint8Array`	Base64 blob content (`mimeType` defaults to `application/octet-stream`)
Plain object / array	JSON-serialized text content (`mimeType` forced to `application/json`)
`null` / `undefined`	Empty text content
`ResourceResult(contents)`	Passed through as-is

When you need full control over the contents array — multiple parts, custom MIME types per part, or hand-built MCP output — return a ResourceResult. It bypasses conversion so what you construct is exactly what the client receives.

server.ts

import { ResourceResult } from '@prefecthq/fastmcp-ts/server'

server.resource({ uri: 'bundle://manifest' }, () => {
  return ResourceResult([
    { uri: 'bundle://manifest', mimeType: 'application/json', text: '{"v":1}' },
  ])
})

Subscriptions

A resource’s value can change after a client has read it, and subscriptions let the client find out instead of polling. Two sides meet here: your server announces that a resource changed, and a subscribed client re-reads it at its own pace. Announce a change from server code with server.notifyResourceUpdated(uri). Call it whenever the data behind a URI changes — after a write, on a timer, or from an event handler. FastMCP delivers notifications/resources/updated to every connection that subscribed to that URI and nothing to the rest, so calling it for a URI with no subscribers is safe and cheap. The notification carries only the URI, never the new value, which keeps updates light; each client re-reads the fresh data when it is ready to use it.

server.ts

import { FastMCP } from '@prefecthq/fastmcp-ts/server'

const server = new FastMCP({ name: 'my-server' })
let settings = { theme: 'dark' }

server.resource({ uri: 'config://settings' }, () => JSON.stringify(settings))

// Later, when the settings change:
settings = { theme: 'light' }
server.notifyResourceUpdated('config://settings')

notifyResourceUpdated is the single change signal for both protocol eras. The wire transport differs underneath — a legacy client subscribes with the resources/subscribe and resources/unsubscribe RPCs, while a modern client opens one long-lived subscriptions/listen stream — but your server calls the one method and FastMCP routes the notification to each subscriber on its own era. The legacy subscribe and unsubscribe requests both run through your middleware chain, and subscribe honors a resource’s auth guard exactly as a read does. Subscribing is a client-side action, so the subscribe API lives on the client. The client passes a handler that fires on each update.

client.ts

await client.subscribeResource('config://settings', (uri) => {
  console.log(`${uri} changed — re-read it`)
})

await client.unsubscribeResource('config://settings')

The handler fires whenever the server sends notifications/resources/updated for that URI. Because the notification names only the URI, the client reads the fresh value on its own schedule.

Variable completion

When a resource is a template, each RFC 6570 variable can suggest values as the client fills it in. The complete config field maps a variable name to a completion callback, and a completion/complete request for that template routes to the matching callback. This lets a client offer real identifiers for {id} rather than expecting the user to already know them. Each callback receives the partial value the user has typed and an optional context holding the template’s other resolved variables, and it returns a plain string[] or a CompletionResult with explicit total and hasMore hints. The callback may be async, so it can query a store. Completion applies to templates only — a static URI has no variables to complete.

server.ts

server.resource(
  {
    uri: 'user://{id}',
    description: 'User by ID',
    complete: {
      id: async (value) => {
        const ids = await listUserIds()
        return ids.filter((id) => id.startsWith(value))
      },
    },
  },
  ({ id }) => `User #${id}`,
)

FastMCP caps a bare string[] to the 100-item wire maximum and computes total and hasMore for you. The same callback shape completes prompt arguments.

Configuration

Beyond uri and the display metadata, the config object accepts these fields. Each is optional and each shapes how the resource is advertised or read.

Field	Behavior
`uri`	Required; a static URI or an RFC 6570 template
`name`, `title`, `description`	Display metadata, forwarded verbatim in list responses
`mimeType`	Overrides the inferred MIME type
`size`	Size hint in bytes; static resources only, since the size of a parameterized URI is unknown, so it is omitted from template listings
`annotations`	`audience`, `priority`, and `lastModified`, forwarded verbatim to clients
`timeout`	Per-read timeout in milliseconds; a handler that exceeds it propagates as an error to the client
`disabled`	When `true`, hides the resource from listings and rejects reads
`tags`	Free-form strings read by transforms
`auth`	Per-resource authorization check — see Authorization
`complete`	Completion callbacks for a template’s RFC 6570 variables, keyed by variable name; templates only

Dynamic registration

You can register a resource before or after server.run(). Adding one to a running server sends notifications/resources/list_changed to connected clients automatically, exactly as adding a tool sends the tools notification — the registration system is uniform across the three primitives.

server.ts

// Later, while the server is already running
server.resource({ uri: 'status://current' }, () => 'ok')
// connected clients receive resources/list_changed

Get Started

Concepts

Servers

Authentication

Advanced Servers

Apps

Clients

More

Registration

URI templates

Return values

Subscriptions

Variable completion

Configuration

Dynamic registration

​Registration

​URI templates

​Return values

​Subscriptions

​Variable completion

​Configuration

​Dynamic registration

Registration

URI templates

Return values

Subscriptions

Variable completion

Configuration

Dynamic registration