---
schema_version: "1"
id: afe7959f6e4ce8ad1c67d478058df7c3af563260e69da9d0168f1f092dc31ca0
title: MCP Payload Optimization Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-mcp-payload-optimization.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-payload-optimization
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 2df210ee1c5017886370ecd9b4c0d69eccb9357883eb51825f3983613d5bf001
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Payload Optimization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Payload Optimization Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Reduces tool response token consumption using one or more configurable methods: remove structural noise, trim oversized responses to match agent intent, or compress repeated structures into TOON</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-payload-optimization-release-notes">MCP Payload Optimization</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Payload Optimization policy reduces LLM token consumption by transforming MCP `tools/call`
responses before they’re returned to the client. The policy operates in three configurable stages:

1.  **Clean Payloads** - Removes structural noise and unnecessary data:

    - Convert HTML to Markdown

    - Remove base64-encoded data

    - Remove JSON fields with null values

    - Remove excessive whitespace

2.  **Smart Response Trimming** - Uses a model proxy to reduce large responses to match the agent’s
    intent, extracting only the information the agent requires.

3.  **Compress Repeated Structures** - Encodes uniform JSON structures into Token-Oriented Object
    Notation (TOON), a lossless format that reduces tokens.

The policy processes responses when:

- The upstream response has a `Content-Type` of `application/json` or `text/event-stream` (SSE).

- The body is a JSON-RPC MCP `tools/call` result (including streamed SSE events that carry those
  results).

Configure the minimum response size to skip transformation for small payloads. Each stage has
independent size thresholds.

The policy uses the `pre_transform_tokens` and `response_tokens` for tool metrics to estimate token
reduction.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Payload Optimization policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>HTML to Markdown</p></div></div></td><td><div><div><p>Converts HTML content in tool results to Markdown.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Strip Base64</p></div></div></td><td><div><div><p>Detects and removes base64-encoded data from tool results.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Remove Nulls</p></div></div></td><td><div><div><p>Removes JSON fields whose value is null.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Collapse Whitespace</p></div></div></td><td><div><div><p>Removes excess whitespace in text content.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Min Response Size (bytes)</p></div></div></td><td><div><div><p>Minimum response size in bytes to transform. Smaller responses pass through unchanged for the four Token Sanitization transforms (<code>HTML to Markdown</code>, <code>Strip Base64</code>, <code>Remove Nulls</code>, <code>Collapse Whitespace</code>). Doesn’t limit TOON encoding or smart response trimming, which have their own thresholds. Minimum value is <code>0</code>.</p></div></div></td><td><div><div><p><code>500</code></p></div></div></td></tr><tr><td><div><div><p>Enable Compress Repeated Structures</p></div></div></td><td><div><div><p>Translates JSON-shaped <code>result.content[].text</code> items to TOON to reduce downstream LLM tokens. For more information, see <a href="#compress-repeated-structures">Compress Repeated Structures</a>.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>TOON Min Response Size (bytes)</p></div></div></td><td><div><div><p>Minimum response size in bytes for TOON encoding. Responses smaller than this skip TOON encoding. Minimum value is <code>0</code>.</p></div></div></td><td><div><div><p><code>500</code></p></div></div></td></tr><tr><td><div><div><p>Enable Smart Response Trimming</p></div></div></td><td><div><div><p>When enabled, a model proxy distills large tool responses down to match the caller’s declared intent (the <code>expected_info</code> of the request), reducing tokens returned to the model.For more information, see <a href="#smart-response-trimming">Smart Response Trimming</a>.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Model Proxy URL</p></div></div></td><td><div><div><p>The endpoint of the model proxy service used for Smart Response Trimming (for example, <code><a href="http://llmproxy.svc.cluster.local/v1/chat/completions">http://llmproxy.svc.cluster.local/v1/chat/completions</a></code>). Must be an OpenAI-compatible <code>/chat/completions</code> endpoint. Required when Smart Response Trimming is enabled.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Model Proxy ID</p></div></div></td><td><div><div><p>Identifier of the selected Model Proxy asset, stored for reference. This value is parsed and retained but not used at runtime by the policy.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Model-Based Routing</p></div></div></td><td><div><div><p>Determines how the model proxy selects the target model. When disabled (default), the proxy owns model selection (Semantic Routing). When enabled, the caller selects the model via the <code>LLM Model</code> parameter (Model-Based Routing).</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>LLM Model</p></div></div></td><td><div><div><p>Model name sent in the <code>/chat/completions</code> request body (for example, <code>gpt-4o-mini</code>). Required when <strong>Model-Based Routing</strong> is enabled.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Client ID</p></div></div></td><td><div><div><p>Client ID for model proxy authentication. Sent as a <code>client_id</code> request header.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Client Secret</p></div></div></td><td><div><div><p>Client secret for model proxy authentication. Sent as a <code>client_secret</code> request header.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Threshold Bytes</p></div></div></td><td><div><div><p>Smart Response Trimming runs only when the post-sanitize content length exceeds this threshold (in bytes). Payloads below this threshold pass through with sanitize-only results.</p></div></div></td><td><div><div><p><code>8000</code></p></div></div></td></tr><tr><td><div><div><p>LLM Timeout (ms)</p></div></div></td><td><div><div><p>Timeout in milliseconds for each model proxy request. If the proxy exceeds this timeout, the call fails and only completes the <strong>Clean Payloads</strong> step.</p></div></div></td><td><div><div><p><code>10000</code></p></div></div></td></tr><tr><td><div><div><p>Per-Tool Overrides</p></div></div></td><td><div><div><p>Overrides the policy configuration values for specific tool names. Tools without an override use the global policy configuration. To learn more, see <a href="#tool-overrides">Per-tool overrides</a>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr></tbody></table>

### Per-tool overrides

Use **Per-Tool Overrides** to override the response optimization of specific tools. For example, if
whitespace is necessary for a specific tool response but not for others, override **Collapse
Whitespace** for that tool.

You can override the global policy configuration for the **HTML to Markdown**, **Strip Base64**,
**Remove Nulls**, and **Collapse Whitespace** parameters. You cannot override **Min Response Size**,
**TOON Min Response Size**, **Enable Compress Repeated Structures**, or **Smart Response Trimming**
on a per-tool basis. Both TOON encoding and Smart Response Trimming are global settings that apply
to all eligible tool responses.

If you omit a parameter in an override configuration, the tool uses the corresponding value from the
global policy configuration.

#### Example per-tool override

For a tool that legitimately returns base64-encoded images, you can disable **Strip Base64** for
that specific tool:

```yaml
tool_overrides:
  - tool_name: generate_image
    strip_base64: false
```

## Transformation Order

The policy applies optimizations in three stages:

### Stage 1: Clean Payloads

String transforms are applied to each eligible string value in this order:

1.  **HTML to Markdown** — Converts HTML documents or fragments to Markdown.

2.  **Strip Base64** — Replaces detected base64 blobs with a short `<stripped: N bytes>`
    placeholder.

3.  **Collapse Whitespace** — Normalizes runs of whitespace.

Then the structural transform is applied:

4.  **Remove Nulls** — Removes JSON fields with null values (applied once after string transforms).

### Stage 2: Smart Response Trimming

When enabled, Smart Response Trimming runs after Token Sanitization:

5.  **Intent Extraction** — A model proxy distills the sanitized content to match the agent’s
    declared intent, reducing token count further.

### Stage 3: Compress Repeated Structures

When enabled, TOON encoding runs last:

6.  **TOON Encoding** — Encodes eligible JSON content items into TOON format (runs on
    already-cleaned and optionally-extracted content).

## Smart Response Trimming

Smart Response Trimming uses a model proxy to distill large tool responses to match the agent’s
declared intent. When enabled, the policy:

1.  Applies the Token Sanitization transforms (HTML to Markdown, Strip Base64, Collapse Whitespace,
    Remove Nulls).

2.  Checks if the sanitized content exceeds the **Threshold Bytes** parameter (default: 8000 bytes)
    and includes `expected_info`

3.  Sends the sanitized content to the configured model proxy.

4.  Replaces the original content with the LLM extracted response if it’s smaller than the sanitized
    version.

Smart Response Trimming:

- Requires a model proxy endpoint configured via **Model Proxy URL**.

- Requires `expected_info` to be present and non-empty in the request. The extractor only runs when
  the caller declares their intent.

- Is fail-open. If there is any LLM failure (timeout, transport error, non-2xx status), the policy
  falls back to the result from **Clean payloads**.

- Processes `content[0]` only when it is `type: "text"`. Other content entries are left untouched.

- Uses client credentials (**Client ID** and **Client Secret**) for model proxy authentication, sent
  as separate `client_id` and `client_secret` request headers (not HTTP Basic Auth).

- Includes an output guard that rejects extractions larger than the sanitized input.

- Makes exactly one LLM call per response.

- Works with both JSON (`application/json`) and Server-Sent Event (`text/event-stream`) responses.
  When enabled, SSE responses are buffered to allow complete content extraction.

## Compress Repeated Structures

TOON is a compact, lossless, JSON-equivalent text format that reduces LLM token consumption for
structured data. When **Enable Compress Repeated Structures** is enabled, the policy translates
eligible JSON-shaped content items into TOON format.

TOON encoding:

- Runs after all other transforms.

- Applies to only the shapes that TOON can shrink, for example, uniform-scalar arrays of objects.

- Preserves or reduces payload size (never inflates).

- Is a global setting with no per-tool overrides.

- Uses the **TOON Min Response Size (bytes)** threshold, independent of the **Min Response Size
  (bytes)** threshold used for other transforms.

A payload can be large enough for TOON encoding but too small for Token Sanitization transforms, or
vice versa, because they use independent thresholds.

## See Also

- [MCP Support Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-support)