Back to Documentation

Cache Control

Intelligent caching that reduces costs, improves latency, and gives agents full control over freshness.

Cache Transparency

MCPify exposes complete cache metadata to agents, enabling intelligent decisions about data freshness:

{
  "result": {...},
  "_meta": {
    "cache": {
      "status": "hit",
      "age_seconds": 127,
      "ttl_remaining": 173,
      "etag": "W/"abc123"",
      "last_modified": "2025-08-25T10:15:00Z",
      "stale_while_revalidate": true
    }
  }
}

Multi-Layer Caching

L1: Edge Cache

CDN-level caching for static resources and public data. Sub-10ms response times globally.

TTL: 1-24 hours • Scope: Global

L2: Gateway Cache

MCPify gateway cache for API responses. Shared across all agents for the same tenant.

TTL: 5-60 minutes • Scope: Tenant

L3: Session Cache

Per-conversation cache for agent working memory. Persists across tool calls in a session.

TTL: 1-6 hours • Scope: Session

Cache Invalidation

Agents can explicitly control cache behavior through dedicated tools:

// Force fresh data
{
  "tool": "get_customer",
  "arguments": {
    "id": "cust_123",
    "force_refresh": true  // Bypasses cache
  }
}

// Invalidate specific cache entry
{
  "tool": "cache.invalidate",
  "arguments": {
    "pattern": "customer:cust_123"
  }
}

// Clear all cache for a service
{
  "tool": "cache.clear",
  "arguments": {
    "service": "crm_api",
    "scope": "tenant"
  }
}

Cache Key Strategy

MCPify generates stable, deterministic cache keys:

Key Components

  • • Service: API identifier
  • • Endpoint: Tool or resource path
  • • Parameters: Sorted, normalized query params
  • • Auth Context: User/tenant isolation
  • • Version: Schema version for compatibility
crm:v2:customers:list:status=active&limit=20:tenant_abc123

Smart Cache Policies

Stale-While-Revalidate

Serve stale data immediately while fetching fresh data in the background:

{
  "cache_policy": {
    "ttl": 300,
    "stale_while_revalidate": 60,
    "stale_if_error": 86400
  }
}

Semantic Caching

Cache similar queries together using embedding similarity:

{
  "semantic_cache": {
    "enabled": true,
    "similarity_threshold": 0.95,
    "embedding_model": "text-embedding-3-small"
  }
}

Conditional Requests

Use ETags and Last-Modified headers for efficient revalidation:

GET /api/resource
If-None-Match: "W/\"abc123\""
If-Modified-Since: Mon, 25 Aug 2025 10:00:00 GMT

// 304 Not Modified (no body, use cached)

Configuration Example

{
  "cache": {
    "enabled": true,
    "default_ttl": 300,
    "max_age": 86400,
    "strategies": {
      "/api/users/*": {
        "ttl": 1800,
        "key_params": ["id", "fields"],
        "vary_headers": ["Authorization"]
      },
      "/api/search": {
        "ttl": 60,
        "semantic": true,
        "stale_while_revalidate": 30
      },
      "/api/realtime/*": {
        "bypass": true
      }
    },
    "invalidation": {
      "on_mutation": ["POST", "PUT", "DELETE"],
      "webhook": "https://api.example.com/cache-invalidate"
    }
  }
}

Ready to optimize with intelligent caching?

Cache control lets you trade freshness for cost and latency, per tool.

Get StartedBrowse the docs