Skip to content

CONCEPT Cited by 1 source

Resource link vs embedded resource

Definition

Resource link vs embedded resource is the token-budget / bandwidth trade-off that emerges when an MCP tool returns resource-typed content. MCP defines two tool-response content types for this purpose:

  • resource_link — the tool returns a URI and metadata only. The client decides when (or whether) to fetch the resource content. Enables client-side caching, update notifications via resources/updated, and on-demand hydration.
  • resource (embedded) — the tool inlines the full resource content in the tool response. One fewer roundtrip to produce content; one less lever for the client to avoid re-transmitting the same bytes on repeated invocations.

(Source: sources/2026-01-08-wix-mcp-resources-all-you-need-to-know).

The decision rule

Verbatim from the Wix tutorial:

You should avoid embedded resource if content is large or frequently reused. In such cases, by returning a link instead of content, you allow the client to avoid reloading full content repeatedly after it has already been fetched.

Paraphrased rule of thumb:

Content size Reuse frequency Recommended shape
Small Low Either — embedded is simpler
Small High resource_link — client caches once
Large Low resource_link — defer fetch until needed
Large High resource_link — the canonical win

Response shapes

Resource link (from a tool handler):

return {
  content: [{
    type: 'resource_link',
    name,
    uri,                 // same URI as the resource registration
    mimeType: 'text/plain',
  }],
};

Embedded resource (from a tool handler):

return {
  content: [{
    type: 'resource',
    resource: {
      uri,               // same URI as the resource registration
      mimeType: 'text/plain',
      text: '...',       // full content inlined
    },
  }],
};

Critical invariant per Wix: the URI in either shape must match the URI used when the resource was registered, so the client can (a) deduplicate against the client-side cache, and (b) listen for notifications/resources/updated on the same URI when the resource is updatable.

Why this matters at agent scale

This is the outbound analogue of the MCP context-window problem the wiki has canonicalised from the inbound direction:

A related inbound-direction lever from the same family is Dash's "store tool results locally rather than inline them into the context window" — Dropbox's concrete implementation on the tool-result side of the same principle.

Seen in

Last updated · 476 distilled / 1,218 read