Zero-Code Compliance for Any MCP Server

1. The Problem

Your MCP server runs tools. Those tools make decisions, access data, and take actions on behalf of users. When an auditor asks "what did the AI do?", the answer is usually application logs.

Application logs were never designed to be compliance evidence. They can be incomplete, modified, or lost. They lack cryptographic integrity. They do not map to regulatory controls. They are not independently verifiable.

The Witness Middleware creates a cryptographic witness record for every tool call your server processes (or a deterministic fraction, if you configure sampling). Each record proves which tool ran, how long it took, and whether it succeeded. The record is anchored by a SHA-256 fingerprint that anyone can independently recompute. If a single bit changes, the hash breaks. That is the difference between a log entry and evidence.

2. One Line of Code

import { withSWT3 } from "@tenova/swt3-mcp/middleware";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = withSWT3(new StdioServerTransport(), {
  apiKey: process.env.SWT3_API_KEY,
});
await server.connect(transport);

// Drain buffered evidence before exit
process.on("SIGTERM", async () => {
  await transport.flush();
  process.exit(0);
});

This wraps the communication layer between your server and the MCP client. Your tool handlers run exactly as before. The middleware buffers witness payloads and flushes them in batches. The flush() call on shutdown ensures no evidence is lost when the process exits. See Batching and Graceful Shutdown for details.

No API key? Omit it entirely. The middleware runs in demo mode and logs witness records to stderr. No network calls, no account required. Upgrade to a free account when you want persistent evidence.

3. What Happens When a Tool Runs

Each witness record is anchored to the AI-TOOL.1 procedure in the Universal Control Taxonomy. This maps directly to EU AI Act Art. 12 (record-keeping), NIST AI RMF MEASURE 2.5, and OWASP Agentic Top 10 controls for tool abuse prevention.

4. When to Use This

SWT3 offers three integration levels. Choose based on how much compliance depth your system requires.

This guide covers Level 1 (the middleware). For framework-specific configuration recipes that combine all three levels into copy-paste regulatory compliance configs, see the Regulatory Configuration Recipes guide.

5. Configuration

All settings are optional. The middleware runs with zero configuration in demo mode.

6. Batching and Graceful Shutdown

By default, the middleware buffers witness payloads and flushes them in batches of 10 (or every 5 seconds, whichever comes first). This reduces network overhead from one HTTP call per tool invocation to one call per batch.

Graceful Shutdown

withSWT3() returns the transport with a flush() method attached. Call it before your process exits to drain any remaining payloads.

const transport = withSWT3(new StdioServerTransport(), {
  apiKey: process.env.SWT3_API_KEY,
});
await server.connect(transport);

// On shutdown:
process.on("SIGTERM", async () => {
  await transport.flush();
  process.exit(0);
});

If you call transport.close() instead (the standard MCP transport lifecycle), the middleware flushes automatically before closing. If the flush fails, the close still completes. Evidence delivery is best-effort; transport teardown is never blocked.

The flush timer uses .unref() so it will not keep a Node.js process alive after all other work is done. You do not need to explicitly clean up the timer.

Tuning for Real-Time vs. Throughput

// Real-time evidence (every tool call flushed immediately)
withSWT3(transport, { batchSize: 1 });

// High-throughput server (batch up to 50, flush every 10s)
withSWT3(transport, { batchSize: 50, flushIntervalMs: 10_000 });

7. Sampling

High-volume servers may not need to witness every single tool call. The middleware supports deterministic sampling: given the same fingerprint input, the same witness/skip decision is made every time. This is not random. It is reproducible.

// Witness 10% of tool calls globally
withSWT3(transport, {
  apiKey: process.env.SWT3_API_KEY,
  samplingRate: 0.1,
});

Per-Tool Overrides

Critical tools can be witnessed at a higher rate than routine ones. Per-tool rates override the global rate.

withSWT3(transport, {
  apiKey: process.env.SWT3_API_KEY,
  samplingRate: 0.01,   // 1% for everything else
  samplingRates: {
    "execute_trade": 1.0,    // 100% for trades
    "modify_account": 1.0,   // 100% for account changes
    "health_check": 0.0,     // never witness health checks
  },
});

Why Deterministic Sampling Matters to Assessors

The sampling algorithm is identical across all SWT3 implementations (Python, TypeScript, Go, Rust, C#, Ruby, Swift), producing the same sampling decisions for the same input across all languages.

8. Multi-Tenant

If your MCP server handles requests from multiple tenants, the middleware can resolve the correct tenant for each tool call at runtime.

withSWT3(transport, {
  apiKey: process.env.SWT3_API_KEY,
  tenantId: "DEFAULT_TENANT",
  resolveTenant: (toolName, params) => {
    // Extract tenant from the tool call parameters
    return params.tenant_id;
  },
});

The callback receives the tool name and the full JSON-RPC params object. Return a tenant ID string, or undefined to fall back to the configured tenantId.

Each payload in the batch carries its own tenant_id field. A single batch can contain payloads for multiple tenants. The server routes each payload to the correct tenant ledger.

The resolved tenant is also used in the fingerprint formula, so fingerprints are always scoped to the correct tenant. Cross-tenant fingerprint collisions are not possible.

9. Retry

Network failures and server errors do not lose evidence. The middleware maintains an in-memory retry queue for failed batches.

Retries piggyback on the flush interval timer. There are no extra timers or background threads. Each flush cycle checks the retry queue first, sends any eligible batches (past their backoff delay), then flushes new payloads.

The retry queue is bounded at maxRetryBuffer payloads (default: 500). If the queue overflows, the oldest batches are evicted first. After maxRetries attempts (default: 3), the batch is dropped and error receipts are fired via onWitness.

10. Real-World Patterns

Production MCP Server

A typical production configuration combines batching, sampling, signing, and retry. This is the recommended starting point for regulated environments.

const transport = withSWT3(new StdioServerTransport(), {
  apiKey: process.env.SWT3_API_KEY,
  agentId: "claims-processor-v3",
  signingKey: process.env.SWT3_SIGNING_KEY,
  clearingLevel: 2,

  // Batching: flush every 20 payloads or 10 seconds
  batchSize: 20,
  flushIntervalMs: 10_000,

  // Sampling: witness all trades, 10% of reads, skip health checks
  samplingRate: 0.1,
  samplingRates: {
    "execute_trade": 1.0,
    "modify_account": 1.0,
    "health_check": 0.0,
  },

  // Retry: 3 attempts with exponential backoff
  maxRetries: 3,

  // Observability: pipe receipts to your logging stack
  onWitness: (receipt) => {
    logger.info("swt3.witness", {
      tool: receipt.toolName,
      fingerprint: receipt.fingerprint,
      error: receipt.error ?? null,
    });
  },
});
await server.connect(transport);

process.on("SIGTERM", async () => {
  await transport.flush();
  process.exit(0);
});

Observability Pipeline

Pipe witness receipts into your existing observability stack. Every tool call becomes a structured event in Datadog, Splunk, CloudWatch, or any system that accepts structured logs.

withSWT3(transport, {
  apiKey: process.env.SWT3_API_KEY,
  onWitness: (receipt) => {
    logger.info("swt3.tool.witnessed", {
      tool: receipt.toolName,
      fingerprint: receipt.fingerprint,
      latency_ms: receipt.latencyMs,
      error: receipt.error ?? null,
    });
  },
});

The callback fires for every witnessed tool call when the batch is flushed, regardless of whether the POST succeeded or failed. If the POST failed, receipt.error tells you why. Sampled-out calls do not fire onWitness (they appear in AI-SAMPLE.1 summaries instead). The tool call itself is never affected.

Signed Anchors for Regulated Environments

When evidence may be disputed, HMAC-SHA256 signatures bind each anchor to the holder of the signing key. The signature proves the anchor was minted by an authorized system, not reconstructed after the fact.

withSWT3(transport, {
  apiKey: process.env.SWT3_API_KEY,
  signingKey: process.env.SWT3_SIGNING_KEY,
  agentId: "claims-processor-v3",
});

Register the signing key server-side to enable verification. Every anchor minted by this agent carries a tamper-evident signature.

Minimal Metadata for Classified Environments

Clearing level 3 strips all descriptive metadata. Tool names are hashed. Only numeric factors (call count, latency, success/failure) and the cryptographic fingerprint leave the wire. The evidence proves something happened without revealing what.

withSWT3(transport, {
  apiKey: process.env.SWT3_API_KEY,
  clearingLevel: 3,
});

11. Common Questions

12. What This Does Not Do

Getting Started

Install the package:

npm install @tenova/swt3-mcp

Import the middleware, wrap your transport, and connect. Every tool call your server processes now produces a cryptographic witness record (or a deterministic fraction, if you configure sampling). Start in demo mode, verify the output, then connect to the ledger when you are ready.

• MCP server setup guide
• Full MCP governance guide
• npm package
• Create a free account
• SDK documentation