Surface MCP Rate-Limit and Request-ID Headers

Before you start

You need a working Cloudinary MCP server connection in your client — Asset Management, Environment Config, Structured Metadata, Analysis or MediaFlows — and the ability to edit the configuration entry for it. Remote servers authenticate over OAuth and local servers take manual credentials, so if you have not settled that yet, decide OAuth or API key headers before changing anything else. MCP server access is included on every plan, Free included, so there is no tier to upgrade to first.

You also need to know which Admin API rate limits apply to you. On the Free plan that is 500 Admin API requests per hour; other features carry their own ceilings, described in the Admin API reference.

Steps

1. Decide whether you are in a build phase or a steady-state phase. Embedded headers cost context: every tool result grows by a few hundred tokens, on every call, for the whole session. That is worth paying while you are building an integration and working out where the ceilings actually bite. It is rarely worth paying once the integration is stable and its call volume is known. If several servers are already connected, that overhead compounds — see the context cost of leaving several MCP servers connected before you turn it on everywhere.

2. Set cloudinary-embed-headers to true in the server’s entry in your MCP client configuration, following the option as documented in the Cloudinary MCP server reference. The setting is per server, so enable it on the one you are actually debugging rather than all five.

3. Restart the MCP client so it re-reads the configuration. MCP clients read server configuration at startup and negotiate capabilities during initialization, per the Model Context Protocol specification; an edited config file has no effect on a session already running.

4. Call one tool and read the _headers object in the result. It carries three values that matter for pacing: the rate-limit ceiling for that feature, the remaining allowance, and the reset timestamp. Without them, the limit is discovered by receiving an error — one full round trip after the point where the caller could have paced itself. With them, the agent knows the remaining allowance before it decides how many calls to issue next.

5. Use the remaining allowance to gate fan-out. This is the reason limit visibility matters more under agent workloads than human ones: an agent that fans out over an asset list can exhaust an hourly allowance in a burst that a person would have spread over an afternoon. Read remaining before starting a batch, and stop or wait for the reset timestamp rather than discovering the ceiling mid-run. If the fan-out itself is the problem, restricting which tools the server exposes narrows what the model can call in the first place.

6. Record the request ID when a call fails or behaves oddly. The same _headers object carries a request ID. It is the only value that ties a vendor support ticket to the exact call an agent made — an agent session produces many similar calls, and without the ID a ticket describes a category of request rather than a specific one. Copy it out of the tool result before the session ends.

7. Turn the option back off once the integration is stable. The pacing information stops being new after you know the ceilings and have written the batch sizes into your code; the per-call token cost does not stop. Leave it on only for the server you are actively debugging.

What done looks like

Every tool result from the configured server contains a _headers object with the feature’s rate-limit ceiling, the remaining allowance, the reset timestamp and a request ID. The agent can check the remaining allowance before a fan-out instead of learning the limit from a failed call, and any call you need to raise with Cloudinary support can be identified exactly.