@armalo/mcp-shield

Drop-in trust boundary for MCP servers. Free, OSS, no Armalo account required.

@armalo/mcp-shield wraps your MCP tool handlers with four layers of defense before they ever execute:

1. Trust-score gating — if the calling agent's Armalo composite score is below your threshold, the call is rejected. Anonymous callers bypass this layer.
2. Per-tool rate limits — token-bucket limits keyed by (toolName, callerAgentId), with both per-minute and per-day windows.
3. Prompt-injection prefilter — a curated list of high-signal markers (OWASP LLM01, MCP tool-poisoning patterns) blocks the most common attack strings.
4. Audit forwarding — every accepted call and every rejection is fire-and-forget POSTed to an audit webhook, with secrets redacted.

Install

# Programmatic use
pnpm add @armalo/mcp-shield

# Scaffold a config file (no install needed)
npx armalo-mcp-shield init

Quick start

import { createMcpShield } from '@armalo/mcp-shield';

const shield = createMcpShield({
  agentId: 'your-mcp-server-uuid',
  policy: {
    defaultMinTrustScore: 600,
    perTool: {
      transfer_funds: {
        minTrustScore: 800,
        rateLimit: { perMinute: 5, perDay: 100 },
      },
      delete_everything: { deny: true },
    },
  },
  failClosed: true,
});

const shieldedHandler = shield.wrapTool('transfer_funds', async (args) => {
  // Your original tool logic — only runs after every check passes.
  return doTransfer(args);
});

Callers identify themselves via either an _armaloCallerAgentId arg or an X-Armalo-Caller HTTP header. If neither is supplied, trust-gating is skipped for that call (rate-limit + injection-filter still apply, keyed to anonymous).

HTTP middleware (Express / Fastify)

import express from 'express';
import { createMcpShield } from '@armalo/mcp-shield';

const shield = createMcpShield({ policy: { defaultMinTrustScore: 500 } });

const app = express();
app.use(express.json());
app.post('/mcp', shield.middleware, yourMcpHandler);

The middleware inspects JSON-RPC tools/call requests, applies the same checks as wrapTool, and rejects with a 403 (or 429 on rate-limit) before your handler is reached.

CLI

armalo-mcp-shield init           # scaffold armalo-mcp-shield.config.json
armalo-mcp-shield wrap server.ts # generate server.shielded.ts wrapper
armalo-mcp-shield healthcheck    # validate config + emit diagnostics
armalo-mcp-shield --version

Standalone mode (no Armalo API key)

Leave armaloApiKey unset and set policy.defaultMinTrustScore: 0 to disable the trust-oracle network call. You still get rate-limiting and injection filtering — useful for a quick safety net on personal servers.

Upgrade to the hosted dashboard

The OSS shield is the runtime. For per-tool analytics, cross-server policy, managed allowlists, anomaly alerts, and a searchable audit log, the hosted dashboard at armalo.ai/products/mcp-shield is $29/mo via Whop. Same package, drop in an armaloApiKey and auditWebhookUrl, and your data shows up in your console.

License

MIT