te limit reset timestamps, and provider capability metadata. Jitter must be applied to prevent thundering herd scenarios, and queue position must be tracked to avoid overwhelming the provider.

Step 5: Generate Deterministic Exhaustion Denials

When a budget is exhausted, the system must return a typed denial. This denial includes attempt count, elapsed time, quota owner, protected provider, next retry window, and allowed recovery actions. The model must never improvise a workaround around a spent budget.

Step 6: Attach Comprehensive Trace Receipts

Every attempt must generate a structured receipt. The receipt reconstructs the loop without relying on post-hoc LLM explanations. It captures route identifiers, operation classes, budget consumption, provider responses, backoff decisions, and policy outcomes.

Implementation Architecture (TypeScript)

The following implementation demonstrates a budget-first router. It separates concerns into explicit interfaces: SideEffectClassifier, QuotaLane, BackoffStrategy, and RetryReceipt.

interface RouteBudget {
  maxAttempts: number;
  wallClockMs: number;
  providerCallCap: number;
  tokenLimit: number;
  costLimitCents: number;
}

interface QuotaLane {
  owner: 'tenant' | 'workspace' | 'provider_account';
  identifier: string;
  credentialScope: 'primary' | 'fallback' | 'test';
}

interface OperationClass {
  type: 'read' | 'search' | 'estimate' | 'write' | 'send' | 'purchase' | 'delete';
  requiresIdempotencyKey: boolean;
}

interface BackoffStrategy {
  baseDelayMs: number;
  maxDelayMs: number;
  jitterFactor: number;
  respectRetryAfter: boolean;
}

interface RetryReceipt {
  routeId: string;
  toolCallId: string;
  operationClass: OperationClass;
  quotaLane: QuotaLane;
  attemptNumber: number;
  maxAttempts: number;
  elapsedMs: number;
  providerStatus: number;
  retryAfterMs?: number;
  idempotencyKey?: string;
  backoffDelayMs: number;
  policyDecision: 'continue' | 'exhausted' | 'denied';
  denialCode?: string;
  allowedRecovery: string[];
}

class BudgetedMCPRouter {
  private activeReceipts: Map<string, RetryReceipt[]> = new Map();

  constructor(
    private readonly budget: RouteBudget,
    private readonly lane: QuotaLane,
    private readonly classifier: OperationClass,
    private readonly backoff: BackoffStrategy
  ) {}

  async executeWithBudget(
    routeId: string,
    toolCallId: string,
    executor: () => Promise<{ status: number; headers: Record<string, string>; body?: unknown }>
  ): Promise<RetryReceipt> {
    const receiptChain: RetryReceipt[] = this.activeReceipts.get(toolCallId) || [];
    let currentAttempt = receiptChain.length;
    const startTime = Date.now();

    while (currentAttempt < this.budget.maxAttempts) {
      const elapsed = Date.now() - startTime;
      if (elapsed > this.budget.wallClockMs) {
        return this.generateDenial(toolCallId, routeId, currentAttempt, elapsed, 'WALL_CLOCK_EXCEEDED', ['fallback_to_cached', 'notify_user']);
      }

      const attemptReceipt = await this.runAttempt(toolCallId, routeId, currentAttempt, executor);
      receiptChain.push(attemptReceipt);
      this.activeReceipts.set(toolCallId, receiptChain);

      if (attemptReceipt.policyDecision === 'continue') {
        const delay = this.calculateBackoff(attemptReceipt);
        await this.sleep(delay);
        currentAttempt++;
      } else {
        return attemptReceipt;
      }
    }

    return this.generateDenial(toolCallId, routeId, currentAttempt, Date.now() - startTime, 'BUDGET_EXHAUSTED', ['escalate_to_human', 'queue_for_retry_window']);
  }

  private async runAttempt(
    toolCallId: string,
    routeId: string,
    attempt: number,
    executor: () => Promise<{ status: number; headers: Record<string, string>; body?: unknown }>
  ): Promise<RetryReceipt> {
    try {
      const response = await executor();
      
      if (response.status === 200) {
        return this.buildReceipt(toolCallId, routeId, attempt, 200, 'continue', []);
      }

      if (response.status === 429 || response.status === 503) {
        const retryAfter = response.headers['retry-after'] 
          ? parseInt(response.headers['retry-after'], 10) * 1000 
          : undefined;
        
        if (!this.classifier.requiresIdempotencyKey && this.classifier.type !== 'read') {
          return this.buildReceipt(toolCallId, routeId, attempt, response.status, 'denied', ['verify_side_effect_status']);
        }

        return this.buildReceipt(toolCallId, routeId, attempt, response.status, 'continue', [], retryAfter);
      }

      return this.buildReceipt(toolCallId, routeId, attempt, response.status, 'denied', ['inspect_error_payload']);
    } catch (error) {
      return this.buildReceipt(toolCallId, routeId, attempt, 0, 'continue', ['retry_with_backoff']);
    }
  }

  private calculateBackoff(receipt: RetryReceipt): number {
    const base = this.backoff.baseDelayMs * Math.pow(2, receipt.attemptNumber);
    const capped = Math.min(base, this.backoff.maxDelayMs);
    const jitter = capped * this.backoff.jitterFactor * (Math.random() * 2 - 1);
    const finalDelay = Math.max(0, capped + jitter);
    
    if (this.backoff.respectRetryAfter && receipt.retryAfterMs && receipt.retryAfterMs > finalDelay) {
      return receipt.retryAfterMs;
    }
    return finalDelay;
  }

  private buildReceipt(
    toolCallId: string,
    routeId: string,
    attempt: number,
    status: number,
    decision: 'continue' | 'denied' | 'exhausted',
    recovery: string[],
    retryAfter?: number
  ): RetryReceipt {
    return {
      routeId,
      toolCallId,
      operationClass: this.classifier,
      quotaLane: this.lane,
      attemptNumber: attempt + 1,
      maxAttempts: this.budget.maxAttempts,
      elapsedMs: 0,
      providerStatus: status,
      retryAfterMs: retryAfter,
      idempotencyKey: this.classifier.requiresIdempotencyKey ? this.deriveIdempotencyKey(toolCallId) : undefined,
      backoffDelayMs: 0,
      policyDecision: decision,
      allowedRecovery: recovery
    };
  }

  private generateDenial(
    toolCallId: string,
    routeId: string,
    attempts: number,
    elapsed: number,
    code: string,
    recovery: string[]
  ): RetryReceipt {
    return {
      routeId,
      toolCallId,
      operationClass: this.classifier,
      quotaLane: this.lane,
      attemptNumber: attempts,
      maxAttempts: this.budget.maxAttempts,
      elapsedMs: elapsed,
      providerStatus: 0,
      policyDecision: 'exhausted',
      denialCode: code,
      allowedRecovery: recovery
    };
  }

  private deriveIdempotencyKey(toolCallId: string): string {
    return `idemp_${toolCallId}_${Date.now()}`;
  }

  private sleep(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

Architecture Rationale

Why separate side-effect classification? Reads and writes fail differently. A failed read can be retried immediately. A failed write requires idempotency verification to prevent duplicate charges or messages. The classifier enforces this boundary at the router level, not the model level.

Why explicit exhaustion denials? Agents will attempt to bypass limits if given ambiguity. A typed denial with a denialCode and allowedRecovery array forces the orchestrator to follow a predefined path. This prevents model improvisation and keeps the system within budget.

Why trace receipts over logs? Logs are append-only and unstructured. Receipts are stateful, queryable, and tied to specific tool calls. They enable operators to reconstruct the exact sequence of attempts, backoff decisions, and policy violations without parsing free-text output.

Why provider metadata alignment? Generic backoff ignores rate limit reset windows. Parsing Retry-After and provider reset timestamps ensures the system pauses until the provider is actually ready, reducing wasted attempts and provider pressure.

Pitfall Guide

1. Global Retry Middleware Trap

Explanation: Applying a single retry policy across all MCP tools ignores the fundamental difference between idempotent reads and destructive writes. A payment endpoint and a search endpoint share the same backoff curve, causing duplicate transactions or unnecessary provider load. Fix: Route-level budget contracts must declare side-effect classes. Apply aggressive retry only to read/search operations. Enforce idempotency keys and status lookups for write/send/purchase classes.

2. False Idempotency Assumption

Explanation: Assuming an endpoint is idempotent because its name contains create_or_update or upsert. Many providers do not accept stable idempotency keys, or they treat subsequent calls as updates rather than safe replays. Fix: Verify idempotency against provider documentation, not endpoint naming. Implement explicit idempotency key generation and require provider acknowledgment. If the provider lacks native support, implement application-level deduplication using request hashes.

3. Ignoring Provider Call Caps

Explanation: Tracking token consumption while ignoring the number of provider API calls. Provider quotas are often the scarcest resource, and token budgets do not prevent rate limit exhaustion. Fix: Include providerCallCap in the route budget. Decrement the counter on every HTTP request, regardless of token count. Alert when the provider call budget reaches 80% capacity.

4. Fallback as Hidden Retry Path

Explanation: Routing to a secondary provider when the primary fails, without establishing a separate budget, credential lane, or data-use policy. This silently consumes unapproved credits and bypasses tenant consent. Fix: Treat fallback routing as a distinct transaction. Require explicit budget allocation, separate credential management, and tenant authorization before switching providers. Log the fallback decision in the receipt.

5. Logging Only Final Success

Explanation: Recording only the successful response while discarding intermediate 429 responses, timeouts, and backoff decisions. This makes it impossible to audit why the system retried or how much quota was consumed. Fix: Attach a structured receipt to every attempt. Store the full attempt chain in a queryable trace store. Ensure the final receipt references all prior attempts, provider responses, and policy decisions.

6. Model-Driven Route Bypass

Explanation: Allowing the LLM to choose alternative endpoints or providers when rate limits are hit. The model lacks financial context and will optimize for task completion over budget preservation. Fix: Remove routing discretion from the model. Enforce budget exhaustion denials with predefined recovery actions. The orchestrator, not the model, decides whether to queue, escalate, or terminate.

7. Missing Exhaustion Denial Contract

Explanation: Returning a generic error when retries are exhausted. The agent receives no structured guidance on what to do next, leading to undefined behavior or silent failures. Fix: Return a typed denial containing denialCode, elapsedMs, quotaOwner, nextRetryWindow, and allowedRecovery. The orchestrator must parse this contract and execute the prescribed recovery path.

Production Bundle

Action Checklist

• Define route-level budgets: Set max attempts, wall-clock ceiling, provider call cap, and cost limit per tool endpoint.
• Classify side effects: Tag every MCP tool with an operation class (read, write, send, purchase, delete) and idempotency requirement.
• Isolate quota lanes: Assign explicit ownership (tenant, workspace, provider account) and credential scope (primary, fallback, test) to each route.
• Align backoff with provider metadata: Parse Retry-After headers and rate limit reset timestamps; apply jitter to prevent thundering herd.
• Enforce idempotency verification: Generate stable keys for write operations; require provider acknowledgment before replaying.
• Structure exhaustion denials: Return typed denial contracts with attempt counts, elapsed time, quota owner, and allowed recovery actions.
• Attach trace receipts: Log every attempt with route ID, tool call ID, provider status, backoff delay, and policy decision in a queryable format.
• Test failure fixtures: Force 429, 503, timeout-after-write, and duplicate intent scenarios; verify receipts match expected contracts.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Read-heavy search endpoints	Aggressive retry with short backoff, no idempotency required	Reads are safe to repeat; high availability prioritized over strict quota conservation	Low; token cost scales linearly with attempts
Write/Purchase endpoints	Strict idempotency enforcement, single retry with status lookup	Prevents duplicate charges/messages; provider acceptance requires verification	Medium; idempotency key generation adds minimal overhead
Multi-tenant workspaces	Tenant-scoped quota lanes with isolated budgets	Prevents noisy neighbor exhaustion; ensures fair resource distribution	High; requires tenant-aware routing and billing attribution
Fallback provider routing	Separate budget allocation, explicit credential lane, data-use policy	Prevents unapproved spend; maintains compliance and auditability	High; dual-provider licensing and routing complexity
Unattended agent fleets	Budget exhaustion denials with predefined recovery paths	Eliminates model improvisation; ensures deterministic loop termination	Low; reduces runaway retry storms and provider penalties

Configuration Template

mcp_route_budget:
  route_id: "tool_calendar_create_event"
  operation_class: "write"
  requires_idempotency: true
  
  quota_lane:
    owner: "tenant"
    identifier: "${TENANT_ID}"
    credential_scope: "primary"
    
  budget_limits:
    max_attempts: 3
    wall_clock_ms: 15000
    provider_call_cap: 5
    token_limit: 4000
    cost_limit_cents: 120
    
  backoff_policy:
    base_delay_ms: 1000
    max_delay_ms: 8000
    jitter_factor: 0.25
    respect_retry_after: true
    
  exhaustion_contract:
    denial_code: "BUDGET_EXHAUSTED"
    allowed_recovery:
      - "queue_for_retry_window"
      - "notify_user_manual_approval"
      - "escalate_to_orchestrator"
      
  trace_requirements:
    include_attempt_chain: true
    capture_provider_headers: true
    store_receipt_ttl_hours: 72

Quick Start Guide

1. Map your tools: Inventory every MCP endpoint and assign an operation class (read, write, send, purchase, delete). Mark which require idempotency keys.
2. Define budgets: Create a RouteBudget object for each tool. Set conservative limits initially (e.g., 3 attempts, 10s wall clock, 5 provider calls). Adjust based on load testing.
3. Implement the router: Instantiate BudgetedMCPRouter with your budget, quota lane, classifier, and backoff strategy. Wrap your tool executor in executeWithBudget().
4. Attach trace storage: Configure a receipt store (Redis, PostgreSQL, or observability platform) to persist RetryReceipt objects. Ensure queries can reconstruct full attempt chains by toolCallId.
5. Validate failure paths: Force 429, 503, and timeout scenarios. Verify that receipts contain correct policy decisions, backoff delays, and exhaustion denials. Confirm the orchestrator respects allowedRecovery actions.