> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Resource Subscriptions

> Publish resource invalidations to active MCP listeners.

Subscriptions let a client keep a live `subscriptions/listen` request open and
receive list or resource invalidations. After an invalidation, the client reads
the affected resource again to obtain current content.

Delivery is listener-bound and non-durable. The stateless HTTP transport does
not store subscriptions in a session, queue missed events, or provide replay
after a listener disconnects.

## Publish resource changes

Define a resource with a stable URI, update its backing data, and publish the
appropriate invalidation:

```typescript theme={null}
import { MCPServer } from "mcp-use";
import { z } from "zod";

const server = new MCPServer({
  name: "settings-server",
  version: "1.0.0",
});

const settingsUri = "settings://app";
let theme = "light";

server.resource({ name: "app-settings", uri: settingsUri }, async (uri) => ({
  contents: [
    {
      uri: uri.href,
      mimeType: "application/json",
      text: JSON.stringify({ theme }),
    },
  ],
}));

server.tool(
  {
    name: "set-theme",
    inputSchema: z.object({ theme: z.enum(["light", "dark"]) }),
  },
  async ({ theme: nextTheme }) => {
    theme = nextTheme;
    await server.notifyResourceUpdated(settingsUri);

    return {
      content: [{ type: "text", text: `Theme changed to ${theme}.` }],
    };
  },
);

export default server;
```

`notifyResourceUpdated(uri)` tells listeners that the representation at one
URI changed; it does not send the new body. Use
`notifyResourcesChanged()` when the discoverable resource or template list
changes:

```typescript theme={null}
await server.notifyResourcesChanged();
```

The related helpers are `notifyToolsChanged()` and
`notifyPromptsChanged()`.

## Design for missed events

Treat notifications as cache invalidations:

* Keep the resource itself authoritative.
* Make reads safe to repeat.
* Do not depend on every intermediate invalidation being delivered.
* Store durable job state, audit history, and workflow progress outside the
  subscription stream.

Use request-scoped custom notifications for status emitted during one active
tool call. See [Notifications](/v2/typescript/server/notifications).

## Test a live listener

Run the maintained notifications example:

```bash theme={null}
cd libraries/typescript/packages/server/examples/notifications
pnpm dev
```

Connect a current MCP client that supports `subscriptions/listen`, keep the
listener request open, and read `example://status`. Call `publish-changes`,
verify that the listener receives the resource invalidation, and read the
resource again. Disconnect the listener and verify that later events are not
replayed when a new listener connects.