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. The result has the same content and structuredContent as the call that filled the cache, and its own _meta.cache is 'hit'

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

A hit is marked on the result’s _meta, not merged into the cached data, so a tool without an outputSchema never finds _meta in its structuredContent or text. A plugin hook that adds result metadata of its own sets the tools:call-tool flow state’s resultMeta the same way: flowCtx.state.set('resultMeta', { ...flowCtx.state.resultMeta, traced: true }).

Cache entries are keyed using a deterministic hash of the tool name, the tool’s validated input, and — by default — the caller’s identity. Two calls share an entry only when all three match, so one user’s response is never served to another. See keyByIdentity below to opt out for data that is identical for every caller.

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, and not shared between servers in one process either: every server gets its own memory store, even when several servers are built from the same app class or CachePlugin.init() result.

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)

boolean

default:"true"

Include the caller’s identity in the cache key.On by default. Most cached tools return something that depends on who is asking — a profile, a balance, a tenant’s records, anything filtered by the caller’s own permissions — and a key built only from the tool and its arguments serves the first caller’s response to everyone else.The identity is the subject your auth layer puts in authInfo.extra (sub / userId), then the client id, then the session. For a request the SDK verified, the client id is the token’s sub, or anon:<id> for an anonymous session. Only a session the server verified (FrontMcpContext.verifiedSessionId) is an identity: the session id the stateless HTTP transport gives every request, the fresh per-request id of a request that sends no mcp-session-id, and an mcp-session-id the server did not accept are not. A call with no identity at all gets a key of its own rather than one shared with every other identity-less caller.

Set this to false only when every caller would get byte-identical output: public reference data, a currency table, a static document. Anything derived from the caller’s permissions, tenant or account must leave it on.

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). 0 (or less) turns caching off for the tool, including when it matches toolPatterns. Up to 1.8.5, ttl: 0 cached the first result with no expiry.

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
ttl: 0 opts out - A tool with cache: { ttl: 0 } is never cached, even when it matches toolPatterns

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

Caller isolation is automatic — the key includes the caller’s identity, so one tenant is never served another’s entry. A tenantId in the input is an ordinary field that selects which data to fetch:

@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 }) {
    // The caller's identity is already in the key; tenantId selects the data
    return await this.fetchTenantData(input.tenantId, input.dataType);
  }
}

The cache key is a SHA-256 digest of the tool name, the validated input and the caller’s identity. Identifiers in the input select what is fetched; they are not what keeps callers apart. Set keyByIdentity: false only when every caller would get byte-identical output.

Session-Scoped Caching

User-specific data needs no special handling — the caller’s identity is part of the key, so each caller gets their own entry:

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 of tool name + validated input + caller identity, so one caller is never served another’s entry. `keyByIdentity: false` drops the identity component — use it only for tools whose output is the same for everybody
Cache Hits	Bypasses tool execution entirely, returns cached result instantly. `content` and `structuredContent` match the call that filled the cache; the result’s `_meta.cache` is `'hit'` (never added to the data itself)
Default TTL	86400 seconds (1 day) if not specified
Sliding Window	Extends TTL on reads when enabled
Store Choice	Memory is per server (one store for each server, even in one process); 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