mcp-guard

KYA (Know Your Agent) security middleware for MCP servers. Abuse database, trust-based access control, rate limiting, and audit logging.

Zero dependencies. Works with any Node.js HTTP framework. Part of the KYA verification system.

Scan any MCP package for security issues: agentscores.xyz - type a package name, get instant results.

---

The Problem

MCP servers have no security layer. Any client can call any tool — there's no identity verification, no access control, no rate limiting, no audit trail. As AI agents begin calling MCP tools autonomously, this is a critical gap.

mcp-guard adds KYA verification to any MCP HTTP server — abuse database checks, trust-based access control, and audit logging in three lines of code.

Install

npm install mcp-trust-guard

Quick Start

import express from 'express';
import { McpGuard } from 'mcp-trust-guard';

const guard = new McpGuard({
  rules: [
    { minTrust: 0,  tools: ['get_*', 'list_*', 'search_*'] },
    { minTrust: 30, tools: ['create_*', 'update_*'] },
    { minTrust: 60, tools: ['delete_*', 'admin_*'] },
  ],
  rateLimit: { window: 60, max: 30 },
  audit: true,
});

const app = express();
app.use(express.json());
app.use('/mcp', guard.middleware());
// ... your MCP server handler

Every tools/call request is now verified against the caller's trust score. Read-only tools are open. Write tools need a score of 30+. Destructive tools need 60+.

How It Works

                                    ┌──────────────┐
Request ──→ Extract Identity ──→ Rate Limit ──→ │  Trust Check │ ──→ Rule Match ──→ Allow/Deny
             (header)            (per caller)    │ (AgentScore) │    (tool pattern)
                                                 └──────────────┘

1. Identity — Reads the caller's agent name from the x-agent-name header (configurable)
2. Rate Limit — Sliding window per caller. Rejects with JSON-RPC error if exceeded
3. Trust Check — Looks up the caller's trust score via AgentScore (5-min cache, fail-closed)
4. Rule Match — Matches the requested tool against your rules using glob patterns. First match wins
5. Allow/Deny — If the caller's score meets the rule's minimum, the request passes through. Otherwise, a JSON-RPC error is returned

Features

Trust-Based Access Control

Define tiered access based on trust scores:

const guard = new McpGuard({
  rules: [
    { minTrust: 0,  tools: ['read_*'] },      // Public — anyone can read
    { minTrust: 20, tools: ['query_*'] },      // Low bar — basic queries
    { minTrust: 40, tools: ['write_*'] },      // Verified agents only
    { minTrust: 70, tools: ['transfer_*'] },   // High trust — financial ops
  ],
  defaultMinTrust: 10, // Tools not matching any rule require score >= 10
});

Tool Name Patterns

Rules use glob patterns with * wildcards:

{ minTrust: 30, tools: ['create_*', 'update_*'] }    // Matches create_user, update_record
{ minTrust: 60, tools: ['admin_*'] }                   // Matches admin_delete, admin_config
{ minTrust: 0,  tools: ['get_status'] }                // Exact match only
{ minTrust: 50, tools: ['*'] }                         // Catch-all

Rate Limiting

In-memory sliding window per caller:

const guard = new McpGuard({
  rateLimit: {
    window: 60,  // 60-second window
    max: 30,     // 30 requests per window per caller
  },
});

Audit Logging

Console logging:

const guard = new McpGuard({ audit: true });
// [mcp-guard] ALLOW EmberFoundry → get_status (score: 42, band: MODERATE TRUST) score 42 >= 0 required for get_status
// [mcp-guard] DENY  untrusted-bot → admin_delete (score: 3, band: UNVERIFIED) score 3 < 60 required for admin_delete

Custom audit handler:

const guard = new McpGuard({
  audit: (entry) => {
    db.insert('audit_log', entry);
    if (!entry.allowed) alerting.notify(`Blocked ${entry.caller} from ${entry.tool}`);
  },
});

Direct Trust Checks

Use the guard programmatically without middleware:

const guard = new McpGuard();

const decision = await guard.check('EmberFoundry', 'transfer_funds');
// { allowed: false, reason: 'score 14 < 70 required for transfer_funds', caller: 'EmberFoundry', trustScore: 14, trustBand: 'UNVERIFIED' }

Custom Trust Providers

Use any trust source — not just AgentScore:

import { McpGuard, TrustProvider, TrustResult } from 'mcp-trust-guard';

const myProvider: TrustProvider = {
  async check(name: string): Promise<TrustResult> {
    const score = await myDatabase.getAgentScore(name);
    return { score, band: score > 50 ? 'TRUSTED' : 'UNTRUSTED', name };
  },
};

const guard = new McpGuard({ provider: myProvider });

Wrapping Any Handler

Not using Express? Wrap any request handler:

const protectedHandler = guard.wrap(mcpHandler);
http.createServer(protectedHandler).listen(3000);

Configuration

Option	Type	Default	Description
provider	TrustProvider	AgentScore	Custom trust score provider
apiUrl	string	https://agentscores.xyz/api/score	AgentScore API endpoint
identityHeader	string	x-agent-name	Header containing caller identity
rules	GuardRule[]	[]	Access rules (first match wins)
defaultMinTrust	number	0	Min trust when no rule matches
rateLimit	{ window, max }	none	Rate limit config (seconds, count)
cacheTtl	number	300000	Trust cache TTL in ms (5 min)
audit	boolean | function	false	Enable audit logging
allowAnonymous	boolean	false	Allow requests without identity

Identifying Callers

By default, mcp-guard reads the caller's identity from the x-agent-name HTTP header. MCP clients should include this header when making requests:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "x-agent-name: MyAgent" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_data"}}'

You can change the header name:

const guard = new McpGuard({ identityHeader: 'authorization' });

Or use query parameters as a fallback — ?agent=MyAgent is checked automatically.

FAQ

What if the trust API is unreachable? The agent gets a score of 0. Fail-closed by default. If your rules allow minTrust: 0 for some tools, those still work.

Does it work with stdio MCP servers? No — stdio servers run locally and don't need network-level security. mcp-guard is for HTTP/SSE MCP servers that accept remote connections.

Does it modify the MCP request? No. It only inspects tools/call requests. All other MCP methods (tools/list, resources/read, etc.) pass through untouched. When a request is allowed, it continues to your handler unchanged.

Can I use my own scoring system? Yes. Implement the TrustProvider interface (one method: check(name) → { score, band, name }) and pass it in the config.

KYA Abuse Database (v0.2.0+)

Block agents that have been reported for abuse — data exfiltration, prompt injection, unauthorized access, and more. Community-driven, free, no API key.

const guard = new McpGuard({
  abuseCheck: true,                // Enable abuse database checks
  abuseBlockLevel: 'CAUTION',      // Block at MONITOR, CAUTION, or BLOCK level
  rules: [
    { minTrust: 0, tools: ['get_*'] },
    { minTrust: 30, tools: ['write_*'] },
  ],
  audit: true,
});

When an agent with abuse reports tries to call a tool:

[mcp-guard] DENY bad-agent → write_file (score: -1, band: ABUSE_REPORTED)
  agent reported in KYA abuse database: prompt_injection (1 reports, severity: high)

Report abuse: POST https://agentscores.xyz/api/abuse/report Check an agent: GET https://agentscores.xyz/api/abuse/check?agent=name

For standalone abuse checking without the full middleware, use kya-abuse-check.

Part of KYA (Know Your Agent)

mcp-trust-guard is the server-side component of KYA — real-time AI agent verification. Six checks: Deployer, Model, Code, Abuse, Permissions, Deployment. No platform registration required.

License

MIT