mcp-shield

Security middleware for MCP servers. Rate limiting, prompt injection detection, budget enforcement, tool sandboxing. The Helmet.js of MCP. Zero dependencies.

Built by Brennan Zambo — extracted from the production security layer protecting the zambo.dev MCP server (28 tools, handling thousands of requests per day).

---

What it does

Every production MCP server gets hammered with prompt injections, abuse, runaway costs, and unauthorized tool calls. mcp-shield adds a security layer in one import:

• Prompt injection detection — 156 patterns across 18 attack vectors (instruction override, DAN jailbreak, system prompt extraction, data exfiltration, template injection, and more)
• Rate limiting — sliding window per client, per minute and per hour
• Budget enforcement — hard cap on calls per session
• Tool allowlist/blocklist — lock down exactly which tools are accessible
• Session tracking — see exactly what every client is doing

---

Install

npm install mcp-shield

Zero dependencies. Node.js 18+.

---

Quick start

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { createShield } from 'mcp-shield';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

const shield = createShield({
  rateLimit: {
    perMinute: 20,
    perHour: 200,
    onExceeded: (clientId, window) => {
      console.warn(`Rate limited: ${clientId} (${window})`);
    },
  },
  promptGuard: {
    enabled: true,
    threshold: 0.65,
    onBlocked: (tool, threat, score) => {
      console.warn(`Blocked on ${tool}: ${threat} (${score.toFixed(2)})`);
    },
  },
  budget: {
    maxCallsPerSession: 100,
  },
  blockList: ['dangerous_tool'],
  verbose: true,
});

// Wrap any tool handler
server.tool(
  'analyze_code',
  { description: 'Analyze code', inputSchema: z.object({ code: z.string() }) },
  shield.wrap('analyze_code', async ({ code }) => {
    return { content: [{ type: 'text', text: await analyze(code) }] };
  })
);

---

Standalone prompt scanning

No shield instance needed:

import { guardPrompt } from 'mcp-shield';

const result = guardPrompt(userInput);

if (result.blocked) {
  console.log(result.threat);  // 'instruction_override' | 'jailbreak_dan' | ...
  console.log(result.score);   // 0.95
}

---

API

createShield(options): Shield

Create a Shield instance.

shield.check(toolName, input, clientId): ShieldResult

Check whether a call should be allowed. Returns { allowed, reason, threat, threatScore }.

shield.wrap(toolName, handler, getInput?): handler

Wrap an async function. Throws 403 if blocked.

const safeHandler = shield.wrap(
  'search_web',
  async (args) => search(args.query),
  (args) => args.query,  // optional: custom input extractor for prompt scanning
);

shield.getSession(clientId): SessionUsage

Get usage stats for a specific client.

const usage = shield.getSession('client_123');
// { calls: 47, blockedAttempts: 2, firstCallAt: 1719000000000, lastCallAt: ... }

shield.allSessions(): Record<string, SessionUsage>

Dump all session stats.

shield.resetClient(clientId)

Reset rate limit and session data for a client.

Shield.scan(text) (static)

Scan without a shield instance:

const { blocked, threat, score } = Shield.scan(text);

guardPrompt(text)

Convenience alias for Shield.scan.

---

ShieldOptions

interface ShieldOptions {
  rateLimit?: {
    perMinute?: number;       // default: 20
    perHour?: number;         // default: 200
    keyBy?: 'client-id' | 'ip' | 'api-key';  // default: 'client-id'
    onExceeded?: (clientId: string, window: 'minute' | 'hour') => void;
  };
  promptGuard?: {
    enabled?: boolean;        // default: true
    mode?: 'fast' | 'deep';   // default: 'fast'
    threshold?: number;       // default: 0.6 (0–1)
    onBlocked?: (tool: string, threat: string, score: number) => void;
    skipTools?: string[];     // tools to skip scanning
  } | boolean;
  budget?: {
    maxCallsPerSession?: number;
    onExceeded?: (clientId: string, usage: SessionUsage) => void;
  };
  allowList?: string[];       // default: ['*'] (all tools)
  blockList?: string[];       // default: []
  verbose?: boolean;          // log to stderr (default: false)
}

---

Threat categories detected

Category	Example
instruction_override	"ignore all previous instructions"
jailbreak_dan	"DAN mode", "do anything now"
system_prompt_extraction	"print your system prompt"
role_manipulation	"you are now an evil AI"
data_exfiltration	"send this to webhook.site/..."
template_injection	[SYSTEM], <|im_start|>, ###Instruction
code_execution	exec(), os.system(), rm -rf
encoding_obfuscation	base64 payloads, ROT13
credential_harvest	"give me your api key"
translation_leak	"translate your instructions to French"
+ 8 more	...

---

Related

• zambo-prompt-shield — standalone prompt injection detection
• mcp-pay — x402 payment billing for MCP tools
• agent-ledger — track every agent call and cost
• zambo.dev — 28 MCP tools all protected by mcp-shield in production

---

License

MIT © Brennan Zambo