@frontmcp/skills 0.0.1 → 1.0.0-beta.9

package/catalog/frontmcp-config/references/configure-http.md

@@ -0,0 +1,205 @@
+# Configuring HTTP Options
+
+Configure the HTTP server — port, CORS policy, unix sockets, and entry path prefix.
+
+## When to Use This Skill
+
+### Must Use
+
+- Changing the default HTTP port or binding to a specific network interface
+- Enabling or restricting CORS for a frontend application that calls the MCP server
+- Binding to a unix socket for local daemon or process-manager integrations
+
+### Recommended
+
+- Mounting the MCP server under a URL prefix behind a reverse proxy
+- Setting a dynamic port from an environment variable for container deployments
+- Fine-tuning CORS preflight caching for performance-sensitive frontends
+
+### Skip When
+
+- Using stdio transport only with no HTTP listener -- no HTTP options apply
+- Only need rate limiting or IP filtering without changing HTTP binding -- use `configure-throttle`
+- Need to configure TLS/HTTPS termination -- handle at the reverse proxy or load balancer level, not in FrontMCP
+
+> **Decision:** Use this skill when you need to customize how the HTTP listener binds (port, socket, prefix) or how it handles CORS; skip if the default port 3001 with permissive CORS is sufficient.
+
+## HttpOptionsInput
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  http: {
+    port: 3001, // default: 3001
+    entryPath: '', // default: '' (root)
+    socketPath: undefined, // unix socket path (overrides port)
+    cors: {
+      // default: permissive (all origins)
+      origin: ['https://myapp.com'],
+      credentials: true,
+      maxAge: 86400,
+    },
+  },
+})
+class Server {}
+```
+
+## Port Configuration
+
+```typescript
+// Default: port 3001
+http: {
+  port: 3001;
+}
+
+// Use environment variable
+http: {
+  port: Number(process.env.PORT) || 3001;
+}
+
+// Random port (useful for testing)
+http: {
+  port: 0;
+}
+```
+
+## CORS Configuration
+
+### Permissive (Default)
+
+When `cors` is not specified, the server allows all origins without credentials:
+
+```typescript
+// All origins allowed (default behavior)
+http: {
+}
+```
+
+### Restrict to Specific Origins
+
+```typescript
+http: {
+  cors: {
+    origin: ['https://myapp.com', 'https://staging.myapp.com'],
+    credentials: true,
+    maxAge: 86400,  // Cache preflight for 24 hours
+  },
+}
+```
+
+### Disable CORS Entirely
+
+```typescript
+http: {
+  cors: false,  // No CORS headers at all
+}
+```
+
+### Dynamic Origin
+
+```typescript
+http: {
+  cors: {
+    origin: (origin: string) => {
+      // Allow any *.myapp.com subdomain
+      return origin.endsWith('.myapp.com');
+    },
+    credentials: true,
+  },
+}
+```
+
+### CORS Fields
+
+| Field         | Type                                        | Default      | Description                        |
+| ------------- | ------------------------------------------- | ------------ | ---------------------------------- |
+| `origin`      | `boolean \| string \| string[] \| function` | `true` (all) | Allowed origins                    |
+| `credentials` | `boolean`                                   | `false`      | Allow cookies/auth headers         |
+| `maxAge`      | `number`                                    | —            | Preflight cache duration (seconds) |
+
+## Entry Path Prefix
+
+Mount the MCP server under a URL prefix:
+
+```typescript
+http: {
+  entryPath: '/api/mcp',
+}
+// Server endpoints become: /api/mcp/sse, /api/mcp/, etc.
+```
+
+Useful when running behind a reverse proxy or alongside other services.
+
+## Unix Socket Mode
+
+Bind to a unix socket instead of a TCP port for local-only access:
+
+```typescript
+http: {
+  socketPath: '/tmp/my-mcp-server.sock',
+}
+```
+
+- Mutually exclusive with `port` — if `socketPath` is set, `port` is ignored
+- Use for local daemons, CLI tools, and process manager integrations
+- Combine with `sqlite` for fully local deployments
+
+## Verification
+
+```bash
+# Start with custom port
+PORT=8080 frontmcp dev
+
+# Test CORS
+curl -v -H "Origin: https://myapp.com" http://localhost:8080/
+
+# Test unix socket
+curl --unix-socket /tmp/my-mcp-server.sock http://localhost/
+```
+
+## Common Patterns
+
+| Pattern               | Correct                                                      | Incorrect                                    | Why                                                                                                               |
+| --------------------- | ------------------------------------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Port from environment | `port: Number(process.env.PORT) \|\| 3001`                   | `port: process.env.PORT`                     | The `port` field expects a number; passing a string causes a silent bind failure                                  |
+| CORS with credentials | `cors: { origin: ['https://myapp.com'], credentials: true }` | `cors: { origin: true, credentials: true }`  | Browsers reject `Access-Control-Allow-Origin: *` when credentials are enabled; you must list explicit origins     |
+| Unix socket mode      | `socketPath: '/tmp/my-mcp.sock'` with no `port` field        | Setting both `socketPath` and `port`         | When `socketPath` is set, `port` is silently ignored which can cause confusion during debugging                   |
+| Entry path prefix     | `entryPath: '/api/mcp'` (no trailing slash)                  | `entryPath: '/api/mcp/'` with trailing slash | Trailing slashes cause double-slash issues in route matching (e.g., `/api/mcp//sse`)                              |
+| Disabling CORS        | `cors: false`                                                | Omitting the `cors` field entirely           | Omitting `cors` applies permissive defaults (all origins allowed); set `false` explicitly to send no CORS headers |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `http` block is present in the `@FrontMcp` decorator metadata
+- [ ] Port value is a number (not a string) and falls within a valid range (0-65535)
+- [ ] If `socketPath` is set, `port` is removed or commented out to avoid confusion
+- [ ] `entryPath` does not have a trailing slash
+
+### CORS
+
+- [ ] If `credentials: true`, `origin` lists explicit allowed origins (not `true` or `*`)
+- [ ] `maxAge` is set to a reasonable value for production (e.g., `86400` for 24 hours)
+- [ ] Dynamic origin function handles `undefined` origin (non-browser requests)
+
+### Runtime
+
+- [ ] Server starts and binds to the expected port or socket path
+- [ ] `curl -v -H "Origin: <your-origin>" <url>` returns correct `Access-Control-Allow-Origin`
+- [ ] Preflight `OPTIONS` requests return `204` with expected CORS headers
+
+## Troubleshooting
+
+| Problem                                          | Cause                                                                                      | Solution                                                                                                |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `EADDRINUSE` on startup                          | Another process is already using the configured port                                       | Change the port, stop the other process, or use `port: 0` for a random available port                   |
+| CORS errors in the browser console               | Origin not included in the `cors.origin` list or `credentials: true` with wildcard origin  | Add the frontend origin to the `origin` array and ensure credentials and origin settings are compatible |
+| Unix socket file not created                     | Missing write permissions on the target directory or stale socket file from a previous run | Check directory permissions and remove the stale `.sock` file before restarting                         |
+| Routes return 404 after setting `entryPath`      | Client is still requesting the root path without the prefix                                | Update client base URL to include the entry path (e.g., `http://localhost:3001/api/mcp`)                |
+| Server binds but external clients cannot connect | Server bound to `localhost` or `127.0.0.1` inside a container                              | Set `host: '0.0.0.0'` or use Docker port mapping to expose the container port                           |
+
+## Reference
+
+- [HTTP Server Docs](https://docs.agentfront.dev/frontmcp/deployment/local-dev-server)
+- Related skills: `configure-throttle`, `configure-transport`, `setup-redis`, `setup-project`

package/catalog/frontmcp-config/references/configure-session.md

@@ -0,0 +1,205 @@
+# Configure Session Management
+
+This skill covers setting up session storage in FrontMCP. Sessions track authenticated user state, token storage, and request context across MCP interactions.
+
+## When to Use This Skill
+
+### Must Use
+
+- Deploying to production where sessions must survive process restarts (Redis or Vercel KV required)
+- Running multiple server instances behind a load balancer that need shared session state
+- Using Streamable HTTP transport where sessions must persist across reconnects
+
+### Recommended
+
+- Configuring session TTL to match your workload pattern (interactive, agent, CI/CD)
+- Namespacing session keys with a unique `keyPrefix` when sharing a Redis instance across multiple servers
+- Setting up Vercel KV for serverless deployments on the Vercel platform
+
+### Skip When
+
+- Running a single-instance local development server -- the default in-memory store is sufficient
+- Using stdio transport only where session persistence is not needed
+- Need to provision Redis itself rather than configure sessions -- use `setup-redis` first, then return here
+
+> **Decision:** Use this skill to choose and configure a session storage provider (memory, Redis, or Vercel KV) and tune TTL and key prefix settings; use `setup-redis` if Redis is not yet provisioned.
+
+## Storage Providers
+
+| Provider    | Use Case            | Persistence | Package Required |
+| ----------- | ------------------- | ----------- | ---------------- |
+| `memory`    | Development/testing | None        | None (default)   |
+| `redis`     | Node.js production  | Yes         | `ioredis`        |
+| `vercel-kv` | Vercel deployments  | Yes         | `@vercel/kv`     |
+
+Never use the memory store in production. Sessions are lost on process restart, which breaks authentication for all connected clients.
+
+## Redis (Production)
+
+Configure Redis session storage via the `@FrontMcp` decorator:
+
+```typescript
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'MyApp' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: Number(process.env['REDIS_PORT'] ?? 6379),
+    password: process.env['REDIS_PASSWORD'],
+  },
+})
+class MyServer {}
+```
+
+The SDK internally calls `createSessionStore()` to create a `RedisSessionStore`. The factory lazy-loads `ioredis` so it is not bundled when you use a different provider.
+
+## Vercel KV
+
+For Vercel deployments, use the `vercel-kv` provider. Credentials are read from environment variables set automatically by the Vercel platform:
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { provider: 'vercel-kv' },
+})
+class MyServer {}
+```
+
+Required environment variables (auto-injected when a KV store is linked to your Vercel project):
+
+| Variable            | Description                    |
+| ------------------- | ------------------------------ |
+| `KV_REST_API_URL`   | Vercel KV REST endpoint        |
+| `KV_REST_API_TOKEN` | Vercel KV authentication token |
+
+## Memory (Development Default)
+
+When no Redis or KV configuration is provided, the SDK falls back to an in-memory store. This is suitable only for development:
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  // No redis config -- defaults to memory
+})
+class MyServer {}
+```
+
+## Key Prefix
+
+All persistent stores support a `keyPrefix` option that namespaces session keys. This is important when multiple FrontMCP servers share the same Redis instance:
+
+```typescript
+@FrontMcp({
+  info: { name: 'billing-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: 'shared-redis.internal',
+    port: 6379,
+    keyPrefix: 'billing-mcp:session:',
+  },
+})
+class BillingServer {}
+```
+
+Use a unique prefix per server to prevent session key collisions.
+
+## TTL Configuration
+
+The `defaultTtlMs` option controls how long sessions live before expiring:
+
+| Scenario                     | Recommended TTL         |
+| ---------------------------- | ----------------------- |
+| Interactive user sessions    | `3_600_000` (1 hour)    |
+| Long-running agent workflows | `86_400_000` (24 hours) |
+| Short-lived CI/CD operations | `600_000` (10 minutes)  |
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: 'localhost',
+    port: 6379,
+    defaultTtlMs: 86_400_000, // 24 hours for agent workflows
+  },
+})
+class MyServer {}
+```
+
+## Pub/Sub for Resource Subscriptions
+
+If your server uses resource subscriptions (clients subscribe to resource change notifications), you need a pub/sub channel. Vercel KV does not support pub/sub, so you must use Redis for the pub/sub channel even when using Vercel KV for sessions:
+
+```typescript
+import { createSessionStore, createPubsubStore } from '@frontmcp/sdk/auth/session';
+
+// Sessions in Vercel KV
+const sessionStore = await createSessionStore({
+  provider: 'vercel-kv',
+  url: process.env['KV_REST_API_URL'],
+  token: process.env['KV_REST_API_TOKEN'],
+});
+
+// Pub/sub requires Redis
+const pubsubStore = createPubsubStore({
+  provider: 'redis',
+  host: process.env['REDIS_HOST'] ?? 'localhost',
+  port: 6379,
+});
+```
+
+## Common Patterns
+
+| Pattern                | Correct                                                                                      | Incorrect                                                                     | Why                                                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Store construction     | Use `createSessionStore()` factory function                                                  | `new RedisSessionStore(client)` direct construction                           | The factory handles lazy-loading, key prefix normalization, and provider detection automatically               |
+| Vercel KV creation     | `const store = await createSessionStore({ provider: 'vercel-kv' })`                          | `const store = createSessionStore({ provider: 'vercel-kv' })` without `await` | The factory is async for Vercel KV; forgetting `await` uses the store before its connection is ready           |
+| Key prefix per server  | `keyPrefix: 'billing-mcp:session:'` unique per server                                        | Same `keyPrefix` across multiple servers sharing one Redis instance           | Shared prefixes cause session key collisions; one server may read or overwrite another's sessions              |
+| Production storage     | `redis: { provider: 'redis', host: '...' }` or `redis: { provider: 'vercel-kv' }`            | Omitting redis config in production (falls back to memory)                    | Memory sessions vanish on restart; all connected clients must re-authenticate and in-flight workflows are lost |
+| Pub/sub with Vercel KV | Separate `pubsub` config pointing to real Redis alongside `redis: { provider: 'vercel-kv' }` | Expecting Vercel KV to handle pub/sub                                         | Vercel KV does not support pub/sub operations; a real Redis instance is required for resource subscriptions    |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `redis` block is present in the `@FrontMcp` decorator with a valid `provider` field (`'redis'` or `'vercel-kv'`)
+- [ ] `keyPrefix` is unique per server when sharing a Redis instance
+- [ ] `defaultTtlMs` matches the workload pattern (1 hour for interactive, 24 hours for agents, 10 minutes for CI/CD)
+
+### Vercel KV
+
+- [ ] `provider: 'vercel-kv'` is set in the `redis` config
+- [ ] `KV_REST_API_URL` and `KV_REST_API_TOKEN` environment variables are present (auto-injected on Vercel)
+- [ ] A separate `pubsub` config pointing to real Redis is provided if resource subscriptions are used
+
+### Runtime
+
+- [ ] Server starts without Redis connection errors in the logs
+- [ ] `redis-cli keys "mcp:session:*"` shows session keys after an MCP request (for Redis provider)
+- [ ] Sessions persist across server restarts (for Redis/Vercel KV providers)
+- [ ] Sessions expire after the configured TTL
+
+## Troubleshooting
+
+| Problem                                | Cause                                                          | Solution                                                                                       |
+| -------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Sessions lost after server restart     | Using the default in-memory store in production                | Configure `redis: { provider: 'redis' }` or `redis: { provider: 'vercel-kv' }` for persistence |
+| `ECONNREFUSED` on startup              | Redis is not running or host/port is incorrect                 | Start the Redis container (`docker compose up -d redis`) or verify connection details          |
+| Vercel KV `401 Unauthorized`           | Missing or invalid KV tokens                                   | Check `KV_REST_API_URL` and `KV_REST_API_TOKEN` in the Vercel dashboard and redeploy           |
+| Session key collisions between servers | Multiple servers share the same Redis instance and `keyPrefix` | Set a unique `keyPrefix` per server (e.g., `billing-mcp:session:`, `api-mcp:session:`)         |
+| Pub/sub not working with Vercel KV     | Vercel KV does not support pub/sub operations                  | Add a separate `pubsub` config pointing to a real Redis instance                               |
+
+## Reference
+
+- [Session Storage Docs](https://docs.agentfront.dev/frontmcp/deployment/redis-setup)
+- Related skills: `setup-redis`, `configure-auth`, `configure-transport`, `configure-elicitation`

package/catalog/frontmcp-config/references/configure-throttle.md

@@ -0,0 +1,229 @@
+# Configuring Throttle, Rate Limits, and IP Filtering
+
+Protect your FrontMCP server with rate limiting, concurrency control, execution timeouts, and IP filtering — at both server and per-tool levels.
+
+## When to Use This Skill
+
+### Must Use
+
+- Deploying a server to production where abuse protection and rate limiting are required
+- Exposing expensive or destructive tools that need concurrency caps and execution timeouts
+- Restricting access by IP address with allow/deny lists for compliance or security
+
+### Recommended
+
+- Enforcing per-session or per-IP request quotas to ensure fair resource distribution
+- Adding global concurrency limits to prevent server overload under burst traffic
+- Configuring distributed rate limiting across multiple server instances with Redis
+
+### Skip When
+
+- Running a local development server with stdio transport only -- throttle adds unnecessary overhead
+- Only need CORS or port configuration without rate limiting -- use `configure-http`
+- Need authentication or session management rather than rate limiting -- use `configure-session` or `configure-auth`
+
+> **Decision:** Use this skill when your server needs protection against abuse, rate limiting, concurrency control, IP filtering, or execution timeouts at either the server or per-tool level.
+
+## Server-Level Throttle (GuardConfig)
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  throttle: {
+    enabled: true,
+
+    // Global rate limit (all requests combined)
+    global: {
+      maxRequests: 1000,
+      windowMs: 60000, // 1 minute window
+      partitionBy: 'global', // shared across all clients
+    },
+
+    // Global concurrency limit
+    globalConcurrency: {
+      maxConcurrent: 50,
+      partitionBy: 'global',
+    },
+
+    // Default limits for individual tools (applied unless tool overrides)
+    defaultRateLimit: {
+      maxRequests: 100,
+      windowMs: 60000,
+    },
+    defaultConcurrency: {
+      maxConcurrent: 10,
+    },
+    defaultTimeout: {
+      executeMs: 30000, // 30 second timeout
+    },
+
+    // IP filtering
+    ipFilter: {
+      allowList: ['10.0.0.0/8', '172.16.0.0/12'], // CIDR ranges
+      denyList: ['192.168.1.100'],
+      defaultAction: 'allow', // 'allow' | 'deny'
+      trustProxy: true, // trust X-Forwarded-For
+      trustedProxyDepth: 1, // proxy depth to trust
+    },
+  },
+})
+class Server {}
+```
+
+## Per-Tool Rate Limiting
+
+Override server defaults on individual tools:
+
+```typescript
+@Tool({
+  name: 'expensive_query',
+  description: 'Run an expensive database query',
+  inputSchema: {
+    query: z.string(),
+  },
+  outputSchema: { rows: z.array(z.record(z.unknown())) },
+
+  // Per-tool limits
+  rateLimit: {
+    maxRequests: 10,
+    windowMs: 60000,
+    partitionBy: 'session', // per-session rate limit
+  },
+  concurrency: {
+    maxConcurrent: 3,
+    queueTimeoutMs: 5000, // wait up to 5s for a slot
+    partitionBy: 'session',
+  },
+  timeout: {
+    executeMs: 60000, // 60 second timeout for this tool
+  },
+})
+class ExpensiveQueryTool extends ToolContext {
+  async execute(input: { query: string }) {
+    const db = this.get(DB_TOKEN);
+    return { rows: await db.query(input.query) };
+  }
+}
+```
+
+## Configuration Types
+
+### RateLimitConfig
+
+| Field         | Type                            | Default    | Description               |
+| ------------- | ------------------------------- | ---------- | ------------------------- |
+| `maxRequests` | `number`                        | —          | Max requests per window   |
+| `windowMs`    | `number`                        | `60000`    | Window duration in ms     |
+| `partitionBy` | `'global' \| 'ip' \| 'session'` | `'global'` | How to partition counters |
+
+### ConcurrencyConfig
+
+| Field            | Type                            | Default    | Description                                        |
+| ---------------- | ------------------------------- | ---------- | -------------------------------------------------- |
+| `maxConcurrent`  | `number`                        | —          | Max simultaneous executions                        |
+| `queueTimeoutMs` | `number`                        | `0`        | How long to wait for a slot (0 = fail immediately) |
+| `partitionBy`    | `'global' \| 'ip' \| 'session'` | `'global'` | How to partition counters                          |
+
+### TimeoutConfig
+
+| Field       | Type     | Default | Description              |
+| ----------- | -------- | ------- | ------------------------ |
+| `executeMs` | `number` | —       | Max execution time in ms |
+
+### IpFilterConfig
+
+| Field               | Type                | Default   | Description                         |
+| ------------------- | ------------------- | --------- | ----------------------------------- |
+| `allowList`         | `string[]`          | —         | Allowed IPs or CIDR ranges          |
+| `denyList`          | `string[]`          | —         | Blocked IPs or CIDR ranges          |
+| `defaultAction`     | `'allow' \| 'deny'` | `'allow'` | Action when IP matches neither list |
+| `trustProxy`        | `boolean`           | `false`   | Trust X-Forwarded-For header        |
+| `trustedProxyDepth` | `number`            | `1`       | How many proxy hops to trust        |
+
+## Partition Strategies
+
+- **`'global'`** — Single shared counter for all clients. Use for global capacity limits.
+- **`'ip'`** — Separate counter per client IP. Use for per-client rate limiting.
+- **`'session'`** — Separate counter per MCP session. Use for per-session fairness.
+
+## Distributed Rate Limiting
+
+For multi-instance deployments, configure Redis storage in the guard:
+
+```typescript
+throttle: {
+  enabled: true,
+  storage: {
+    type: 'redis',
+    redis: { config: { host: 'redis.internal', port: 6379 } },
+  },
+  global: { maxRequests: 1000, windowMs: 60000 },
+}
+```
+
+## Verification
+
+```bash
+# Start server
+frontmcp dev
+
+# Test rate limiting (send 101 requests rapidly)
+for i in $(seq 1 101); do
+  curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:3001/ \
+    -H 'Content-Type: application/json' \
+    -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+done
+# Should see 429 responses after limit is exceeded
+```
+
+## Common Patterns
+
+| Pattern                   | Correct                                                                                                                        | Incorrect                                                            | Why                                                                                                                                |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Per-tool override         | Set `rateLimit` on the `@Tool` decorator to override server defaults                                                           | Duplicating the full server-level `throttle` config inside each tool | Per-tool config merges with server defaults; only specify the fields you want to override                                          |
+| Partition strategy        | Use `partitionBy: 'session'` for per-user fairness on shared tools                                                             | Using `partitionBy: 'global'` for all limits                         | Global partitioning means one abusive client can exhaust the quota for everyone                                                    |
+| Distributed rate limiting | Configure `storage: { type: 'redis', redis: { config: { host, port } } }` in the throttle block for multi-instance deployments | Relying on in-memory counters with multiple server instances         | In-memory counters are per-process; each instance tracks limits independently, allowing N times the intended rate                  |
+| IP filter ordering        | Set `defaultAction: 'deny'` with an explicit `allowList` for strict environments                                               | Setting `defaultAction: 'allow'` with only a `denyList`              | A deny-by-default posture is safer; new unknown IPs are blocked until explicitly allowed                                           |
+| Concurrency queue timeout | Set `queueTimeoutMs` on concurrency config to queue excess requests briefly                                                    | Setting `queueTimeoutMs: 0` on expensive tools                       | Zero timeout immediately rejects excess requests instead of briefly queuing them, causing unnecessary failures during short bursts |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `throttle.enabled` is set to `true` in the `@FrontMcp` decorator
+- [ ] `global.maxRequests` and `global.windowMs` are set to reasonable production values
+- [ ] `defaultTimeout.executeMs` is configured to prevent runaway tool executions
+- [ ] IP filter `defaultAction` matches your security posture (`allow` for open, `deny` for restricted)
+
+### Per-Tool
+
+- [ ] Expensive or destructive tools have explicit `rateLimit` and `concurrency` overrides
+- [ ] `partitionBy` is set to `'session'` or `'ip'` for tools that need per-client fairness
+- [ ] `queueTimeoutMs` is set on concurrency-limited tools to handle brief bursts
+
+### Distributed
+
+- [ ] Redis storage is configured in the throttle block for multi-instance deployments
+- [ ] Redis connection is verified before deploying (see `setup-redis`)
+
+### Runtime
+
+- [ ] Sending requests beyond the rate limit returns HTTP 429
+- [ ] Blocked IPs receive HTTP 403
+- [ ] Tool executions that exceed `executeMs` are terminated and return a timeout error
+
+## Troubleshooting
+
+| Problem                                         | Cause                                                                    | Solution                                                                        |
+| ----------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| Rate limits not enforced across instances       | In-memory storage used with multiple server replicas                     | Configure `storage: { type: 'redis' }` in the throttle block to share counters  |
+| All requests rejected with 403                  | `ipFilter.defaultAction` set to `'deny'` without any `allowList` entries | Add the allowed IP ranges to `allowList` or change `defaultAction` to `'allow'` |
+| Tools timing out unexpectedly                   | `defaultTimeout.executeMs` too low for the tool's normal execution time  | Increase the global default or set a per-tool `timeout.executeMs` override      |
+| `X-Forwarded-For` header ignored                | `ipFilter.trustProxy` not enabled or `trustedProxyDepth` too low         | Set `trustProxy: true` and adjust `trustedProxyDepth` to match your proxy chain |
+| Rate limit resets not aligned with expectations | `windowMs` misunderstood as a sliding window when it is a fixed window   | The window is fixed; all counters reset at the end of each `windowMs` interval  |
+
+## Reference
+
+- [Guard Configuration Docs](https://docs.agentfront.dev/frontmcp/servers/guard)
+- Related skills: `configure-http`, `configure-transport`, `setup-redis`, `configure-auth`