MCP Server Notifications — types, patterns, and reliable delivery

Notification types at a glance

List-change notifications

List-change notifications tell the client that the catalog of tools, resources, or prompts has changed and it should re-fetch the full list. The notification carries no diff — the client must re-issue the corresponding list request to discover what changed.

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

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

// Emit after dynamic tool registration change
async function enableBetaTools(sessionId: string): Promise<void> {
  // Register the new tools on this session
  registerBetaToolSet(sessionId);
  // Notify the client
  await server.sendToolListChanged();
}

// Emit after resource catalog changes
async function afterCustomerCreated(customerId: string): Promise<void> {
  await server.sendResourceListChanged();
}

// Emit after prompt catalog changes
async function afterFeatureFlagChange(flagName: string, enabled: boolean): Promise<void> {
  if (isPromptFeatureFlag(flagName)) {
    await server.sendPromptListChanged();
  }
}

Coalescing high-frequency list changes. If your data changes rapidly (a stream of row inserts, a webhook fanout), firing a list-change notification per event causes the client to re-fetch the list on every event. Coalesce with a debounce — emit at most one notification per 500ms regardless of how many events fired:

let listChangeDebounce: NodeJS.Timeout | null = null;

function scheduleResourceListChanged(): void {
  if (listChangeDebounce) return; // already pending
  listChangeDebounce = setTimeout(async () => {
    listChangeDebounce = null;
    try {
      await server.sendResourceListChanged();
    } catch (e) {
      console.error('Failed to send resource list changed notification:', e);
    }
  }, 500);
}

Resource update notifications

Resource update notifications are URI-scoped: they tell the client that the content of a specific resource has changed, but only for clients that have subscribed to that URI. The client re-reads the resource after receiving this notification to get the updated content.

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

// Track subscriptions per URI
const subscriptions = new Map<string, Set<string>>(); // uri → sessionIds

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

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

// Emit resource update when content changes
async function onDatabaseRowUpdated(tableName: string, rowId: string): Promise<void> {
  const uri = `db://${tableName}/${rowId}`;
  const subscribers = subscriptions.get(uri);
  if (!subscribers || subscribers.size === 0) return;

  for (const sessionId of subscribers) {
    try {
      await server.sendResourceUpdated({ uri }, sessionId);
    } catch (e) {
      // Session may have disconnected — remove stale subscription
      console.warn(`Failed to notify session ${sessionId} of ${uri} update:`, e);
      subscribers.delete(sessionId);
    }
  }
}

Progress notifications

Progress notifications let a long-running tool report intermediate progress to the client without completing the tool call. The client provides a _meta.progressToken in the tool call parameters; the server emits notifications/progress with monotonically increasing progress values:

server.tool('process_large_dataset', {
  dataset_id: z.string()
}, async ({ dataset_id }, { meta }) => {
  const progressToken = meta?.progressToken;

  const rows = await db.query(
    'SELECT * FROM datasets WHERE id = $1',
    [dataset_id]
  );

  const total = rows.rowCount;
  let processed = 0;

  for (const row of rows.rows) {
    await processRow(row);
    processed++;

    // Emit progress every 100 rows
    if (progressToken && processed % 100 === 0) {
      await server.sendProgress({
        progressToken,
        progress: processed,
        total
      });
    }
  }

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({ processed, total, status: 'complete' })
    }]
  };
});

Rules for progress notifications:

• progress must be monotonically non-decreasing across notifications for the same progressToken.
• total is optional. Omit it if the total is unknown at the start of the operation.
• Never emit progress after the tool call has returned — the client discards progress notifications for completed requests.
• Don't emit progress for short operations (under 1 second). The overhead of notification round-trips is not worth it for fast calls.

Logging notifications

The MCP logging system lets servers emit structured log messages to clients. Clients display these in developer tools, debug panels, or forward them to external log sinks. The client can set the minimum log level via logging/setLevel:

// Declare logging capability
const server = new Server(
  { name: 'my-mcp-server', version: '1.0.0' },
  { capabilities: { tools: {}, logging: {} } }
);

// Current minimum log level (set by client via logging/setLevel)
let minLogLevel: 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency' = 'info';

import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js';
server.setRequestHandler(SetLevelRequestSchema, async ({ params }) => {
  minLogLevel = params.level;
  return {};
});

// Log levels in ascending severity order
const LOG_LEVELS = ['debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency'];

async function mcpLog(
  level: typeof minLogLevel,
  message: string,
  data?: Record<string, unknown>
): Promise<void> {
  // Only emit if level meets minimum threshold
  if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf(minLogLevel)) return;

  try {
    await server.sendLoggingMessage({
      level,
      logger: 'my-mcp-server',
      data: { message, ...data }
    });
  } catch {
    // Logging failure should not affect tool execution
  }
}

// Usage in a tool handler
server.tool('sync_data', { source: z.string() }, async ({ source }) => {
  await mcpLog('info', 'Starting data sync', { source });
  try {
    const result = await syncFromSource(source);
    await mcpLog('info', 'Sync complete', { rows: result.rowCount });
    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
  } catch (e) {
    await mcpLog('error', 'Sync failed', { error: (e as Error).message, source });
    throw e;
  }
});

Notification delivery on SSE vs stdio transports

Notifications are delivered differently depending on the transport:

SSE transport is the most problematic. A client behind a load balancer that terminates idle connections will silently drop the connection; the server's SSE write may queue in the kernel buffer and succeed locally for minutes before failing. Implement an SSE heartbeat (send a comment line : heartbeat\n\n every 30 seconds) to detect dead connections faster, and remove sessions from subscription maps when the SSE stream errors.

// SSE heartbeat for faster dead-connection detection
function startSseHeartbeat(res: express.Response, sessionId: string): NodeJS.Timeout {
  return setInterval(() => {
    try {
      res.write(': heartbeat\n\n');
    } catch {
      // Connection is dead — clean up
      clearInterval(heartbeatTimer);
      cleanupSession(sessionId);
    }
  }, 30_000);
}

Monitoring notification delivery

Add notification metrics to your health endpoint so you know whether notifications are being delivered rather than silently dropped:

const notificationMetrics = {
  sent: 0,
  failed: 0,
  activeSubscriptions: 0,
  activeSessions: 0
};

// Wrap sendResourceUpdated with metric tracking
async function sendResourceUpdatedTracked(params: { uri: string }, sessionId: string): Promise<void> {
  try {
    await server.sendResourceUpdated(params, sessionId);
    notificationMetrics.sent++;
  } catch (e) {
    notificationMetrics.failed++;
    throw e;
  }
}

app.get('/health/notifications', (req, res) => {
  const errorRate = notificationMetrics.sent > 0
    ? notificationMetrics.failed / (notificationMetrics.sent + notificationMetrics.failed)
    : 0;

  const status = errorRate > 0.1 ? 'degraded' : 'ok';

  res.status(status === 'ok' ? 200 : 503).json({
    status,
    metrics: {
      sent: notificationMetrics.sent,
      failed: notificationMetrics.failed,
      error_rate: errorRate.toFixed(3),
      active_subscriptions: [...subscriptions.values()].reduce((s, v) => s + v.size, 0)
    }
  });
});

Wire AliveMCP to /health/notifications. A spike in failed notifications means sessions are disconnecting faster than they're reconnecting — typically a sign of a backend restart, a load balancer timeout, or an upstream network partition that clients are experiencing but your server health check isn't detecting.

Frequently asked questions

Further reading

• MCP Server Resources — resource subscriptions and update notifications
• MCP Capabilities Negotiation — declaring notification capabilities in initialize
• Long-Running Tasks in MCP Servers — progress tokens and async dispatch patterns
• MCP Server Streaming — SSE transport configuration for reliable delivery
• MCP Server Observability — correlating notification metrics with session health