Mcp-Name header rules: rate-limit paid render tools at the gateway

A gateway can throttle paid render tools by name without parsing JSON. MCP 2026-07-28 requires Mcp-Method and Mcp-Name headers on Streamable HTTP POSTs, and x-mcp-header lets selected tool parameters surface as headers too, per the changelog read 2026-10-03. With the tool name in a header, a proxy in front of your own agents can give generate_video a tight limit and jobs_status a loose one.

Heavy tools and cheap tools

Sume's tools page lists paid generation tools (generate_image, generate_video, music_create, tts_create and others) separately from free reads such as jobs_status, assets_list and catalog_list. That split is what a per-name rule needs.

One tool deserves a note: jobs_wait holds an HTTP request for up to 55 seconds, by design. A rule that counts open connections would punish it, so exclude it or give it its own class.

An nginx sketch

The sketch below applies the paid-submit class. Requests whose Mcp-Name header is not listed map to an empty key, and nginx does not rate-limit an empty key. Confirm the header value for tools/call against the spec before you deploy; this example assumes it carries the tool name.

map $http_mcp_name $paid_key {
    default          "";
    generate_image   $binary_remote_addr;
    generate_video   $binary_remote_addr;
    music_create     $binary_remote_addr;
    tts_create       $binary_remote_addr;
}

limit_req_zone $paid_key zone=paid_tools:10m rate=30r/m;

server {
    location /mcp {
        limit_req zone=paid_tools burst=10 nodelay;
        limit_req_status 429;
        proxy_ssl_server_name on;
        proxy_pass https://mcp.sume.com;
    }
}

Do not replace the server's own limits

A gateway rule protects your budget. It does not change Sume's behavior. The errors page lists 429 rate_limited for request volume and 429 queue_full when workspace concurrency plus queue capacity is full, and says to back off using retry-after when it is present. Do not retry an unsafe submit without an Idempotency-Key; on the MCP tools the equivalent is the idempotency_key argument.

Make your gateway return the same status and keep the retry-after header, so a client that handles Sume's limits handles yours.

What headers cannot do

A header names the tool; it does not carry the spend. Use max_spend_usd and dry_run in the tool arguments for that, and expose a parameter as a header with x-mcp-header only when a gateway rule needs it. Keep secrets, prompts and user data out of headers, because proxies log them.