Cache Plugin - AgentFront

The Cache Plugin provides transparent response caching for tools based on their input payloads, reducing redundant computation and improving response time.

Why Use Caching?

Faster Responses

Return cached results instantly without re-executing expensive operations

Reduce Load

Minimize API calls, database queries, and computational overhead

Cost Savings

Lower infrastructure costs by reducing redundant processing

Better UX

Improve perceived performance with instant responses for repeated queries

Installation

npm install @frontmcp/plugin-cache

How It Works

Before Execution

The plugin hashes the tool’s validated input and checks the cache store

Cache Hit

If a cached result exists, it’s returned immediately, bypassing tool execution entirely

Cache Miss

The tool executes normally, and the result is stored with the configured TTL

Sliding Window (Optional)

When enabled, each cache read refreshes the TTL to keep hot entries alive longer

Cache entries are keyed using a deterministic hash of the tool’s validated input. The same input always produces the same cache key.

Quick Start

Basic Setup (In-Memory)

import { App } from '@frontmcp/sdk';
import { CachePlugin } from '@frontmcp/plugin-cache';

@App({
  id: 'my-app',
  name: 'My App',
  plugins: [CachePlugin], // Default: memory store, 1-day TTL
  tools: [
    /* your tools */
  ],
})
export default class MyApp {}

Enable Caching on Tools

Caching is opt-in per tool. Add the cache field to your tool metadata:

import { Tool, ToolContext } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';

@Tool({
  name: 'get-user',
  description: 'Get user by ID',
  inputSchema: { id: z.string() },
  cache: true, // Enable caching with defaults
})
export default class GetUserTool extends ToolContext {
  async execute(input: { id: string }) {
    // Expensive operation (e.g., database query)
    return await this.database.getUser(input.id);
  }
}

import { tool } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';

export const GetUser = tool({
  name: 'get-user',
  description: 'Get user by ID',
  inputSchema: { id: z.string() },
  cache: true, // Enable caching with defaults
})(async (input) => {
  // Expensive operation
  return await database.getUser(input.id);
});

Storage Options

In-Memory (Default)

Best for: Single-instance deployments, development, non-critical caching

CachePlugin.init({
  type: 'memory',
  defaultTTL: 300, // 5 minutes (default: 86400 = 1 day)
});

Memory cache resets when the process restarts. Not shared across multiple instances.

Redis (Recommended for Production)

Best for: Multi-instance deployments, persistent caching, production environments

CachePlugin.init({
  type: 'redis',
  defaultTTL: 600, // 10 minutes
  config: {
    host: '127.0.0.1',
    port: 6379,
    password: process.env.REDIS_PASSWORD, // optional
    db: 0, // optional
  },
});

import { Redis } from 'ioredis';

const redis = new Redis({
  host: 'redis.example.com',
  port: 6379,
});

CachePlugin.init({
  type: 'redis-client',
  defaultTTL: 900, // 15 minutes
  client: redis,
});

Redis enables cache sharing across multiple server instances and persists cache across restarts.

Configuration Options

Plugin-Level Configuration

Configure default behavior when registering the plugin:

'memory' | 'redis' | 'redis-client'

default:"'memory'"

Cache store backend to use

number

default:"86400"

Default time-to-live in seconds (applies to all cached tools unless overridden)

object

Redis connection configuration (required when type: 'redis')

Show properties

string

required

Redis server hostname

number

required

Redis server port

string

Redis authentication password (optional)

number

Redis database number (optional, default: 0)

Redis

Existing ioredis client instance (required when type: 'redis-client')

string[]

Tool names or glob patterns to cache. Tools matching these patterns use defaultTTL unless they have custom cache metadata.

toolPatterns: ['mintlify:*', 'local:ping', 'api:get-*']

string

default:"'x-frontmcp-disable-cache'"

HTTP header name that clients can send to bypass cache for a specific request. When present with value 'true' or '1', cache read/write is skipped.

Tool-Level Configuration

Configure caching behavior per tool in the @Tool or tool() metadata:

@Tool({
  name: 'get-report',
  cache: true, // Uses plugin's defaultTTL
})

@Tool({
  name: 'get-report',
  cache: {
    ttl: 60, // Cache for 1 minute
  },
})

@Tool({
  name: 'get-popular-items',
  cache: {
    ttl: 300, // 5 minutes
    slideWindow: true, // Refresh TTL on each read
  },
})

boolean | object

Enable caching for this tool

true - Use plugin defaults
object - Custom configuration

number

Time-to-live in seconds for this tool’s cache entries (overrides plugin default)

boolean

default:"false"

When true, reading from cache refreshes the TTL, keeping frequently accessed entries alive longer

Caching Remote Tools

For remote MCP tools that you don’t control (connected via URL), use the toolPatterns option to enable caching by name or pattern:

CachePlugin.init({
  type: 'memory',
  defaultTTL: 300, // 5 minutes
  toolPatterns: ['mintlify:*'], // Cache all Mintlify tools
})

CachePlugin.init({
  type: 'redis',
  config: { host: 'localhost', port: 6379 },
  toolPatterns: [
    'external:expensive-query',
    'external:get-user-*', // Glob pattern
  ],
})

@FrontMcp({
  apps: [
    App.remote('https://mintlify.com/docs/mcp', {
      namespace: 'mintlify',
    }),
  ],
  plugins: [
    CachePlugin.init({
      type: 'memory',
      defaultTTL: 300,
      toolPatterns: ['mintlify:*'], // Cache all remote tools
    }),
  ],
})

Pattern Syntax

Pattern	Matches
`tool-name`	Exact match only
`namespace:*`	All tools in namespace
`prefix-*`	Tools starting with prefix
`*-suffix`	Tools ending with suffix
`api:*:list`	Middle wildcard pattern

Priority Rules

Tool metadata takes precedence - If a tool has cache: { ttl: 60 } metadata, that TTL is used
Pattern list uses defaultTTL - Matched tools without metadata use the plugin’s default TTL
Union behavior - A tool is cached if it matches toolPatterns OR has cache metadata

The toolPatterns option is especially useful for remote MCP servers where you can’t add cache: true to tool metadata directly.

Bypassing Cache

Clients can bypass caching for specific requests by sending a header:

# Bypass cache for this request
curl -H "x-frontmcp-disable-cache: true" http://localhost:3000/mcp

Configure a custom header name:

CachePlugin.init({
  type: 'memory',
  bypassHeader: 'x-no-cache', // Custom header name
})

Cache bypass is useful for debugging, forcing fresh data, or when the client knows the cached data is stale.

Advanced Usage

Multi-Tenant Caching

Include tenant or user identifiers in your tool inputs to ensure cache isolation:

@Tool({
  name: 'get-tenant-data',
  inputSchema: {
    tenantId: z.string(),
    dataType: z.string(),
  },
  cache: { ttl: 600 },
})
export default class GetTenantDataTool extends ToolContext {
  async execute(input: { tenantId: string; dataType: string }) {
    // Cache key includes tenantId automatically via input hash
    return await this.fetchTenantData(input.tenantId, input.dataType);
  }
}

The cache key is derived from the entire input object, so including tenant/user IDs ensures proper isolation.

Session-Scoped Caching

For user-specific data, include session or user identifiers:

export const GetUserDashboard = tool({
  name: 'get-user-dashboard',
  inputSchema: {
    userId: z.string(),
    dateRange: z.object({
      start: z.string(),
      end: z.string(),
    }),
  },
  cache: {
    ttl: 120, // 2 minutes
    slideWindow: true,
  },
})(async (input, ctx) => {
  // Cache key includes userId and dateRange
  return await generateDashboard(input.userId, input.dateRange);
});

Time-Based Invalidation

Use short TTLs for frequently changing data:

@Tool({
  name: 'get-live-stock-price',
  inputSchema: { symbol: z.string() },
  cache: {
    ttl: 5, // Only cache for 5 seconds
  },
})

Best Practices

1. Only Cache Deterministic Tools

Cache tools whose outputs depend solely on their inputs. Don’t cache tools that:

Return random data
Depend on external time-sensitive state
Have side effects (mutations, API calls that change state)

2. Choose Appropriate TTLs

Short TTLs (5-60s): Real-time data, frequently changing content - Medium TTLs (5-30min): User dashboards, reports, analytics - Long TTLs (hours-days): Static content, configuration, reference data

3. Use Redis for Production

Redis provides: - Cache persistence across restarts - Sharing across multiple server instances - Better memory management with eviction policies

4. Include Scoping in Inputs

Always include tenant IDs, user IDs, or other scoping fields in your tool inputs:

// Good: includes tenantId for isolation
{ tenantId: "t-123", reportId: "r-456" }

// Bad: no scoping, shared across tenants
{ reportId: "r-456" }

5. Use Sliding Windows for Hot Data

Enable slideWindow for frequently accessed data to keep it cached longer:

cache: {
  ttl: 300,
  slideWindow: true, // Popular items stay cached
}

Cache Behavior Reference

Behavior	Description
Key Derivation	Deterministic hash from validated input. Same input = same cache key
Cache Hits	Bypasses tool execution entirely, returns cached result instantly
Default TTL	86400 seconds (1 day) if not specified
Sliding Window	Extends TTL on reads when enabled
Store Choice	Memory is node-local; Redis enables multi-instance sharing
Invalidation	Automatic after TTL expires, or manually by restarting (memory)

Troubleshooting

No cache hits occurring

Possible causes:

Tool missing cache: true in metadata
Cache store offline or misconfigured
Input varies slightly (whitespace, order of fields)

Solutions:

Verify cache field is set in tool metadata
Check Redis connection if using Redis backend
Ensure input structure is consistent

Stale data being returned

Possible causes:

TTL too long for data freshness requirements
Data changed but cache not invalidated

Solutions:

Reduce TTL for the tool
Consider input-based cache busting (include timestamp or version in input)
Restart server to clear memory cache (or flush Redis)

Cache not shared across instances

Possible cause:

Using memory cache with multiple server instances

Solution:

Switch to Redis backend for multi-instance deployments

Need to invalidate specific cache entries

Solution:

Currently, manual invalidation requires custom implementation
For memory: restart the server
For Redis: use Redis CLI to delete keys manually
Consider shorter TTLs or input-based versioning instead

Complete Example

import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
import { CachePlugin } from '@frontmcp/plugin-cache';
import { z } from '@frontmcp/sdk';

// Configure Redis cache
const cachePlugin = CachePlugin.init({
  type: 'redis',
  defaultTTL: 600, // 10 minutes default
  config: {
    host: process.env.REDIS_HOST || 'localhost',
    port: parseInt(process.env.REDIS_PORT || '6379'),
    password: process.env.REDIS_PASSWORD,
  },
});

// Expensive report generation tool
@Tool({
  name: 'generate-monthly-report',
  description: 'Generate monthly sales report for a tenant',
  inputSchema: {
    tenantId: z.string(),
    month: z.string(), // "2025-01"
  },
  cache: {
    ttl: 1800, // 30 minutes (reports don't change often)
  },
})
class GenerateMonthlyReportTool extends ToolContext {
  async execute(input: { tenantId: string; month: string }) {
    this.logger.info('Generating report', input);

    // Expensive operation: aggregate data, generate charts, etc.
    const report = await this.database.generateReport(input.tenantId, input.month);

    return report;
  }
}

// Hot data with sliding window
@Tool({
  name: 'get-trending-products',
  description: 'Get current trending products',
  inputSchema: {
    category: z.string(),
    limit: z.number().default(10),
  },
  cache: {
    ttl: 120, // 2 minutes
    slideWindow: true, // Keep popular queries cached
  },
})
class GetTrendingProductsTool extends ToolContext {
  async execute(input: { category: string; limit: number }) {
    return await this.analytics.getTrendingProducts(input.category, input.limit);
  }
}

@App({
  id: 'analytics',
  name: 'Analytics App',
  plugins: [cachePlugin],
  tools: [GenerateMonthlyReportTool, GetTrendingProductsTool],
})
class AnalyticsApp {}

@FrontMcp({
  info: { name: 'Analytics Server', version: '1.0.0' },
  apps: [AnalyticsApp],
  http: { port: 3000 },
})
export default class Server {}

Links & Resources

Source Code

View the cache plugin source code

Demo Application

See caching in action with real examples

Plugin Guide

Learn more about FrontMCP plugins

Redis Documentation

Official Redis documentation

​Why Use Caching?

Faster Responses

Reduce Load

Cost Savings

Better UX

​Installation

​How It Works

​Quick Start

​Basic Setup (In-Memory)

​Enable Caching on Tools

​Storage Options

​In-Memory (Default)

​Redis (Recommended for Production)

​Configuration Options

​Plugin-Level Configuration

​Tool-Level Configuration

​Caching Remote Tools

​Pattern Syntax

​Priority Rules

​Bypassing Cache

​Advanced Usage

​Multi-Tenant Caching

​Session-Scoped Caching

​Time-Based Invalidation

​Best Practices

​Cache Behavior Reference

​Troubleshooting

​Complete Example

​Links & Resources

Source Code

Demo Application

Plugin Guide

Redis Documentation

Why Use Caching?

Installation

How It Works

Quick Start

Basic Setup (In-Memory)

Enable Caching on Tools

Storage Options

In-Memory (Default)

Redis (Recommended for Production)

Configuration Options

Plugin-Level Configuration

Tool-Level Configuration

Caching Remote Tools

Pattern Syntax

Priority Rules

Bypassing Cache

Advanced Usage

Multi-Tenant Caching

Session-Scoped Caching

Time-Based Invalidation

Best Practices

Cache Behavior Reference

Troubleshooting

Complete Example

Links & Resources