MCP Server Resources — URI templates, subscriptions, and resource change notifications

Resources vs tools vs prompts

Understanding where resources fit requires a clear picture of all three primitives:

The key distinction between resources and tools: resources are read-only by convention. The MCP spec does not prevent a resource handler from writing data, but clients treat resources as safe to read freely — they may pre-fetch them, cache them, and display them in a resource browser without user confirmation. Write operations belong in tools, not resources.

URI design for MCP resources

MCP resource URIs follow RFC 3986. They must be absolute URIs. The scheme communicates the resource type to clients and shapes client-side rendering decisions:

URI templates (RFC 6570) let you describe a family of resources with a pattern. Use {param} for required path segments and {?query} for optional query parameters. The MCP SDK resolves templates against the incoming URI at read time:

// Static resource — single known URI
server.resource(
  'server-config',
  'config://mcp/server',
  { description: 'Current server configuration' },
  async () => ({
    contents: [{
      uri: 'config://mcp/server',
      mimeType: 'application/json',
      text: JSON.stringify(serverConfig, null, 2)
    }]
  })
);

// Template resource — URI pattern covers a family of resources
server.resource(
  'customer-record',
  new ResourceTemplate('db://customers/{customerId}', { list: undefined }),
  { description: 'Customer record by ID' },
  async (uri, { customerId }) => {
    const customer = await db.customers.findUnique({ where: { id: customerId } });
    if (!customer) throw new Error(`Customer ${customerId} not found`);
    return {
      contents: [{
        uri: uri.href,
        mimeType: 'application/json',
        text: JSON.stringify(customer, null, 2)
      }]
    };
  }
);

Implementing ListResources

The ListResources handler returns the catalog of resources the client can read. Clients use this to populate resource browsers and to decide which resources to include in context before making tool calls. Keep the list actionable — aim for fewer than 50 items; larger catalogs degrade client UI and force LLMs to sift through irrelevant entries.

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { ListResourcesRequestSchema } from '@modelcontextprotocol/sdk/types.js';

const server = new Server(
  { name: 'my-mcp-server', version: '1.0.0' },
  { capabilities: { resources: { subscribe: true, listChanged: true } } }
);

server.setRequestHandler(ListResourcesRequestSchema, async () => {
  const customers = await db.customers.findMany({
    select: { id: true, name: true, updatedAt: true },
    orderBy: { updatedAt: 'desc' },
    take: 20
  });

  return {
    resources: [
      // Static resource — always present
      {
        uri: 'config://mcp/server',
        name: 'Server configuration',
        description: 'Current server runtime configuration and feature flags',
        mimeType: 'application/json'
      },
      // Dynamic resources — one per recent customer
      ...customers.map(c => ({
        uri: `db://customers/${c.id}`,
        name: `Customer: ${c.name}`,
        description: `Customer record last updated ${c.updatedAt.toISOString()}`,
        mimeType: 'application/json'
      }))
    ]
  };
});

The name, description, and mimeType fields are metadata the client uses to select resources. Write clear descriptions — the LLM uses these to decide whether a resource is relevant to include in context before calling a tool.

Implementing ReadResource

The ReadResource handler responds to a specific URI. Return text for UTF-8 string content or blob for base64-encoded binary data. A single resource read can return multiple content items if the URI resolves to a composite view:

import { ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';

server.setRequestHandler(ReadResourceRequestSchema, async ({ params }) => {
  const uri = new URL(params.uri);

  // Route by scheme
  if (uri.protocol === 'config:') {
    return {
      contents: [{
        uri: params.uri,
        mimeType: 'application/json',
        text: JSON.stringify(getServerConfig(), null, 2)
      }]
    };
  }

  if (uri.protocol === 'db:' && uri.hostname === 'customers') {
    const customerId = uri.pathname.slice(1); // remove leading /
    const customer = await db.customers.findUnique({ where: { id: customerId } });
    if (!customer) {
      throw new Error(`Resource not found: ${params.uri}`);
    }
    return {
      contents: [{
        uri: params.uri,
        mimeType: 'application/json',
        text: JSON.stringify(customer, null, 2)
      }]
    };
  }

  if (uri.protocol === 'file:') {
    const filePath = uri.pathname;
    // Validate against declared roots before reading
    if (!isWithinAllowedRoots(filePath)) {
      throw new Error(`Access denied: ${filePath} is outside declared workspace roots`);
    }
    const content = await fs.readFile(filePath, 'utf-8');
    const mimeType = detectMimeType(filePath);
    return {
      contents: [{
        uri: params.uri,
        mimeType,
        text: content
      }]
    };
  }

  throw new Error(`Unsupported resource scheme: ${uri.protocol}`);
});

Always throw a descriptive error for unrecognised URIs rather than returning empty content. Clients surface these errors to the LLM, which uses them to avoid re-requesting the same broken resource.

Resource subscriptions and change notifications

Resources can be subscribed to. When a client subscribes to a URI, the server should notify it when that resource's content changes. This is how a file editor client keeps the LLM's context in sync with file edits without polling on an interval.

import {
  SubscribeRequestSchema,
  UnsubscribeRequestSchema
} from '@modelcontextprotocol/sdk/types.js';

// Track which client sessions have subscribed to which URIs
const subscriptions = new Map<string, Set<string>>(); // uri → Set of sessionIds

server.setRequestHandler(SubscribeRequestSchema, async ({ params }, extra) => {
  const sessionId = extra.sessionId;
  if (!subscriptions.has(params.uri)) {
    subscriptions.set(params.uri, new Set());
  }
  subscriptions.get(params.uri)!.add(sessionId);
  return {};
});

server.setRequestHandler(UnsubscribeRequestSchema, async ({ params }, extra) => {
  subscriptions.get(params.uri)?.delete(extra.sessionId);
  return {};
});

// Emit notifications when a resource changes
async function notifyResourceUpdated(uri: string): Promise<void> {
  const subscribers = subscriptions.get(uri);
  if (!subscribers || subscribers.size === 0) return;

  for (const sessionId of subscribers) {
    await server.sendResourceUpdated({ uri }, sessionId);
  }
}

// Wire to your data change events
db.on('customer:updated', async ({ id }) => {
  await notifyResourceUpdated(`db://customers/${id}`);
});

When the catalog itself changes — resources added or removed — emit a notifications/resources/list_changed notification. Clients re-issue a ListResources request when they receive this, refreshing their resource browser:

async function notifyResourceListChanged(): Promise<void> {
  await server.sendResourceListChanged();
}

// Trigger when a new customer is created or deleted
db.on('customer:created', notifyResourceListChanged);
db.on('customer:deleted', notifyResourceListChanged);

Static versus dynamic resources

Resources split into two operational categories with different monitoring requirements:

Static resources are low-risk. Dynamic resources — especially those backed by database rows or file watchers — require active monitoring. A resource that returns a 200 with stale data is the hardest failure class to detect: the protocol layer looks healthy while the LLM receives outdated context that leads to wrong tool calls.

Resource health endpoint

Expose a /health/resources endpoint that validates the resource layer is operational. Check the three common failure modes: the backing data store is unreachable, the file watcher is dead, and the subscription fanout is accumulating stale sessions.

app.get('/health/resources', async (req, res) => {
  const checks: Record<string, 'ok' | 'degraded' | 'down'> = {};
  const details: Record<string, unknown> = {};

  // 1. Database reachability — can we serve db:// resources?
  try {
    await db.$queryRaw`SELECT 1`;
    checks.db = 'ok';
  } catch (e) {
    checks.db = 'down';
    details.db_error = (e as Error).message;
  }

  // 2. File watcher alive — can we serve file:// resources?
  const watcherAge = Date.now() - lastWatcherHeartbeatMs;
  checks.file_watcher = watcherAge < 30_000 ? 'ok' : 'degraded';
  details.watcher_age_ms = watcherAge;

  // 3. Subscription map size — guard against leaked sessions
  const totalSubscriptions = [...subscriptions.values()]
    .reduce((sum, set) => sum + set.size, 0);
  checks.subscriptions = totalSubscriptions < 1000 ? 'ok' : 'degraded';
  details.subscription_count = totalSubscriptions;

  const overall = Object.values(checks).includes('down') ? 'down'
    : Object.values(checks).includes('degraded') ? 'degraded'
    : 'ok';

  res.status(overall === 'down' ? 503 : 200).json({
    status: overall,
    checks,
    details
  });
});

Wire AliveMCP to this endpoint with a 60-second probe interval. A resource layer failure is silent at the MCP protocol level — ReadResource may continue returning cached data, or may start throwing errors that the LLM interprets as a missing resource rather than a server outage.

Common mistakes

• Returning resource content from tools. If data is read-only and doesn't need user confirmation, it belongs in a resource. Tools that return read-only data cause unnecessary friction and dilute the tool list that affects selection accuracy.
• Listing all rows in a database table. A resource catalog with 10,000 entries is unusable. Apply filters (recent, relevant, owned-by-session) and paginate using nextCursor in the ListResources response.
• Not declaring mimeType. Without mimeType, clients cannot render resource content correctly. At minimum, distinguish text/plain, application/json, and programming language types (text/typescript, text/python).
• Forgetting to validate file paths against roots. If your server exposes file:// resources, validate each requested path against the client-declared roots before reading. See MCP Server Roots for the path validation pattern.
• Subscribing without session cleanup. When a client disconnects, clean up its subscriptions. Leaked sessions in the subscription map cause sendResourceUpdated calls to throw silently for dead connections, inflating error log noise.

Frequently asked questions

Further reading

• MCP Server Prompts — templated interactions and dynamic argument expansion
• MCP Server Roots — filesystem boundary assertions for file:// resources
• MCP Capabilities Negotiation — advertising resource and subscription support
• MCP Server Authentication — per-session identity for resource access control
• MCP Server Tool Discovery — the complementary primitive for write operations