How to harden an existing MCP server without breaking integrations

Why additive hardening is different from rewriting

When you write a new MCP server from scratch, every security control is designed in from the start. A caller that sends a path traversal attempt hits your validation layer and gets a clean error. A caller that hits rate limits gets a 429 response it's expected from the beginning. No client was ever built against the insecure version.

When you harden an existing server, existing callers were built against the insecure behavior. If they're sending what your new validation layer rejects, they break. If they're relying on the verbose error message that leaked your database structure, they break when you sanitize it. The hardening is correct, but you've introduced a breaking change.

The key insight: security controls don't have to be binary on their first day. Most controls can be introduced in an observe → warn → enforce lifecycle that lets you verify no legitimate caller triggers the control before you flip the switch to enforcement.

Phase 1 — Observe (zero behavior change)

// Phase 1: wrap every handler with an observation middleware
// No behavior change — just structured visibility

function observeHandler(toolName, handler) {
  return async (params) => {
    const start = Date.now();
    let result;
    let threw = false;
    try {
      result = await handler(params);
    } catch (err) {
      threw = true;
      throw err;
    } finally {
      const entry = {
        ts: new Date().toISOString(),
        tool: toolName,
        durationMs: Date.now() - start,
        paramKeys: Object.keys(params || {}),
        // Log param shapes (not values) for sensitive fields
        paramTypes: Object.fromEntries(
          Object.entries(params || {}).map(([k, v]) => [k, typeof v])
        ),
        threw,
        isError: result?.isError ?? false,
        responseSize: JSON.stringify(result ?? '').length,
      };
      process.stderr.write(JSON.stringify(entry) + '\n');
    }
    return result;
  };
}

// Wrap all handlers at registration time
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: params } = request.params;
  const handler = observeHandler(name, handlers[name]);
  return handler(params);
});

Run this for 7 days minimum before Phase 2. You'll discover which tools get called most often, what parameter shapes are common, and whether any callers are already hitting what you'd consider invalid inputs. This baseline is your safety net for every subsequent phase.

Phase 2 — Warn-only input validation

// Phase 2: warn-only validation — no enforcement yet
const ENFORCE_VALIDATION = process.env.ENFORCE_VALIDATION === 'true';

function validateInput(toolName, params) {
  const violations = [];

  // Path traversal
  for (const [key, val] of Object.entries(params)) {
    if (typeof val === 'string') {
      if (val.includes('..') || val.includes('\0')) {
        violations.push({ rule: 'PATH_TRAVERSAL', key, pattern: '..' });
      }
      // SSRF: URL params pointing to internal addresses
      if (key.toLowerCase().includes('url')) {
        try {
          const u = new URL(val);
          if (['169.254.169.254', '127.0.0.1', 'localhost', '0.0.0.0'].includes(u.hostname)) {
            violations.push({ rule: 'SSRF_INTERNAL', key, hostname: u.hostname });
          }
        } catch { /* not a URL */ }
      }
      // Command injection metacharacters in fields used in shell contexts
      if (/[;&|`$<>]/.test(val) && (key === 'command' || key === 'args' || key === 'query')) {
        violations.push({ rule: 'CMD_INJECTION_CHARS', key });
      }
    }
  }

  if (violations.length > 0) {
    process.stderr.write(JSON.stringify({
      event: 'VALIDATION_WOULD_REJECT',
      tool: toolName,
      violations,
      ts: new Date().toISOString(),
    }) + '\n');

    if (ENFORCE_VALIDATION) {
      // Return MCP error response (not throw — per MCP error handling spec)
      return {
        content: [{ type: 'text', text: 'Invalid input: ' + violations.map(v => v.rule).join(', ') }],
        isError: true,
      };
    }
  }

  return null; // proceed normally
}

// In handler:
async function readFileTool(params) {
  const rejection = validateInput('readFile', params);
  if (rejection) return rejection;

  // ... existing handler code unchanged ...
}

The critical rule: during warn-only mode, validateInput always returns null, which means the existing handler code runs exactly as before. The only thing that changes is a log line. Existing callers cannot tell the difference.

Phase 3 — Soft rate limiting

// Phase 3: in-process sliding window rate limiter with soft enforcement
const ENFORCE_RATE_LIMITS = process.env.ENFORCE_RATE_LIMITS === 'true';
const RATE_LIMIT_RPM = parseInt(process.env.RATE_LIMIT_RPM || '120', 10);

// Per-caller sliding window using a Map of timestamp arrays
const callerWindows = new Map();

function checkRateLimit(callerId, toolName) {
  const now = Date.now();
  const windowMs = 60_000;
  const key = `${callerId}:${toolName}`;

  if (!callerWindows.has(key)) callerWindows.set(key, []);
  const window = callerWindows.get(key);

  // Evict expired entries
  while (window.length > 0 && window[0] < now - windowMs) window.shift();

  window.push(now);
  const count = window.length;

  if (count > RATE_LIMIT_RPM) {
    process.stderr.write(JSON.stringify({
      event: ENFORCE_RATE_LIMITS ? 'RATE_LIMIT_ENFORCED' : 'RATE_LIMIT_WOULD_THROTTLE',
      tool: toolName,
      caller: callerId,
      countInWindow: count,
      limitRpm: RATE_LIMIT_RPM,
      ts: new Date().toISOString(),
    }) + '\n');

    if (ENFORCE_RATE_LIMITS) {
      return {
        content: [{ type: 'text', text: `Rate limit exceeded: ${RATE_LIMIT_RPM} requests/minute` }],
        isError: true,
      };
    }
  }

  return null;
}

// Clean up old windows every 5 minutes to avoid memory growth
setInterval(() => {
  const cutoff = Date.now() - 70_000;
  for (const [key, ts] of callerWindows) {
    const filtered = ts.filter(t => t > cutoff);
    if (filtered.length === 0) callerWindows.delete(key);
    else callerWindows.set(key, filtered);
  }
}, 5 * 60_000);

Phase 4 — Shadow authentication

// Phase 4a: shadow auth — verify but don't enforce
const AUTH_MODE = process.env.AUTH_MODE || 'shadow'; // 'shadow' | 'soft' | 'enforce'

function checkAuth(request) {
  const authHeader = request.headers?.authorization;

  if (!authHeader) {
    if (AUTH_MODE === 'enforce') {
      return { allowed: false, reason: 'MISSING_TOKEN' };
    }
    // shadow or soft: allow through, log the miss
    process.stderr.write(JSON.stringify({
      event: 'AUTH_WOULD_REJECT',
      reason: 'MISSING_TOKEN',
      ts: new Date().toISOString(),
    }) + '\n');
    return { allowed: true, unauthenticated: true };
  }

  const token = authHeader.replace(/^Bearer /, '');
  const valid = verifyToken(token); // your token verification logic

  if (!valid) {
    if (AUTH_MODE === 'enforce') {
      return { allowed: false, reason: 'INVALID_TOKEN' };
    }
    process.stderr.write(JSON.stringify({
      event: 'AUTH_WOULD_REJECT',
      reason: 'INVALID_TOKEN',
      ts: new Date().toISOString(),
    }) + '\n');
    return { allowed: true, unauthenticated: true };
  }

  return { allowed: true, unauthenticated: false };
}

// Phase 4b (soft mode): add deprecation header to unauthenticated responses
// so clients can see they need to update, without being broken yet
function addDeprecationHint(response, authResult) {
  if (authResult.unauthenticated && AUTH_MODE === 'soft') {
    // MCP doesn't have standard response headers, but HTTP transport can add them
    // Or add a meta field in the response content for stdio
    response._deprecationWarning = 'Authentication will be required in 30 days';
  }
  return response;
}

The coordination step: before moving from soft to enforce, contact every known client author (or update your own client code) and confirm they are sending valid tokens. Only then flip to enforce. This is the one phase where a pure code change is not enough — you need communication alongside it.

Phase 5 — Command injection hardening

// Phase 5: safe command execution with shell-feature detection
const { execFile, exec } = require('child_process');
const { promisify } = require('util');
const execFileP = promisify(execFile);
const execP = promisify(exec);

// Detect shell features that would break if we remove shell: true
const SHELL_FEATURE_RE = /[|&;`$(){}[\]*?~<>!]/;

async function runCommand(binary, args, opts = {}) {
  // args must be an array; never a pre-built shell string
  if (!Array.isArray(args)) {
    throw new Error('runCommand: args must be an array');
  }

  const hasShellFeatures = args.some(a => SHELL_FEATURE_RE.test(a));

  if (hasShellFeatures) {
    // Log the shell feature use — do NOT execute
    process.stderr.write(JSON.stringify({
      event: 'CMD_SHELL_FEATURE_DETECTED',
      binary,
      // Don't log arg values — they may contain secrets or paths
      argCount: args.length,
      ts: new Date().toISOString(),
    }) + '\n');

    // Return an error to the caller, with a non-revealing message
    return {
      content: [{ type: 'text', text: 'Command contains characters not permitted by security policy.' }],
      isError: true,
    };
  }

  // Safe path: no shell, arguments passed as array
  try {
    const { stdout, stderr } = await execFileP(binary, args, {
      timeout: opts.timeout ?? 30_000,
      maxBuffer: opts.maxBuffer ?? 1_048_576,
      env: { PATH: '/usr/local/bin:/usr/bin:/bin' }, // minimal env
    });
    return { content: [{ type: 'text', text: stdout }] };
  } catch (err) {
    // Don't return err.message — may contain path info or stderr
    return {
      content: [{ type: 'text', text: `Command failed with exit code ${err.code ?? 'unknown'}` }],
      isError: true,
    };
  }
}

Most real-world MCP server tools that use exec are wrapping a single binary with user-supplied parameters (a git command, a linter, a converter). These are safe to migrate to execFile immediately. The cases that genuinely need a shell (piped commands) should be replaced with a native implementation that doesn't invoke a shell at all.

Phase 6 — Permission scoping (last, highest risk)

// Phase 6: build a permissions-in-use inventory from Phase 1 logs
// Run this as a one-off analysis script against your structured log:

// Log query (using jq on your JSON-lines log):
// cat access.log | jq -s '[
//   .[] | select(.tool != null) |
//   {tool: .tool, paramKeys: .paramKeys, isError: .isError}
// ] | group_by(.tool) | map({tool: .[0].tool, samples: length, keys: (.[].paramKeys | add | unique)})'

// Permissions mapping built from log analysis:
const PERMISSIONS_INVENTORY = {
  readFile:    { observed: ['fs:read'],          declared: ['fs:read', 'fs:write'] },
  searchFiles: { observed: ['fs:read'],          declared: ['fs:read', 'fs:write', 'net:fetch'] },
  runLinter:   { observed: ['exec:node', 'fs:read'], declared: ['exec:*'] },
};

// For each tool where declared > observed, investigate the gap before narrowing:
for (const [tool, perms] of Object.entries(PERMISSIONS_INVENTORY)) {
  const excess = perms.declared.filter(p => !perms.observed.includes(p));
  if (excess.length > 0) {
    console.log(`${tool}: excess permissions ${excess.join(', ')} — audit source before removing`);
  }
}

Testing strategy: shadow mode and contract tests

The safest pattern for any phase transition is to run the new behavior in shadow alongside the old behavior and compare outputs. For input validation and rate limiting this is straightforward: add the new code path, log what it would have done, compare against the old path.

For behavioral changes (command execution, error messages), write contract tests against the live server before you make the change, capturing exact response shapes. After the change, run the same tests. Any test that breaks is a callsite that needs fixing or an exemption before the change goes out.

// Contract test: capture current behavior as a snapshot before hardening
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import assert from 'assert';

const client = new Client({ name: 'contract-test', version: '1.0.0' });
const transport = new StdioClientTransport({ command: 'node', args: ['./server.js'] });
await client.connect(transport);

// Test: normal path — confirm it still works after Phase 5
const result = await client.callTool('readFile', { path: 'test-fixture.txt' });
assert.equal(result.isError, false);
assert.ok(result.content[0].text.includes('expected content'));

// Test: security violation — confirm it's blocked in enforce mode
const attack = await client.callTool('readFile', { path: '../../etc/passwd' });
assert.equal(attack.isError, true);
// Don't assert on the exact error message text — let it be generic

await client.close();

Realistic timeline and prioritization

A typical existing MCP server can go from a C to a B+ in 30 days following this timeline, with no surprise breaks to existing callers. The full transition to A typically takes 60–90 days — not because the code changes are complex, but because the warn-only observation windows take time and the auth coordination requires communicating with callers.

How SkillAudit scores each phase

SkillAudit doesn't grade on intention — it grades on what the scanner can observe in your published code. Each phase has a corresponding set of checks that the scanner runs:

• Phase 2 (validation): Static analysis for path.join without path.resolve, exec/execSync with concatenated strings, URL construction from input without allowlist checks. Completed Phase 2 moves you from F to C on the Security axis.
• Phase 3 (rate limiting): Presence of a rate limiting implementation in the handler path. Moves Security axis from C to B−.
• Phase 4 (auth): Presence of token verification middleware or equivalent. Moves Security axis to B. Combined with credential exposure fixes (Phase 5 error message hardening), reaches B+.
• Phase 5 (command hardening): Absence of shell: true with variable interpolation. Full elimination of exec/execSync with concatenated input. Moves Security axis to A−.
• Phase 6 (permission scoping): Declared permissions matching the minimal required set inferred from tool implementations. Moves Permissions Hygiene axis from D to A.

Summary

Hardening an existing MCP server is a sequencing problem as much as a coding problem. The code changes for most controls are not complex — the complexity is in running them in observation mode long enough to verify no legitimate caller trips them, then flipping the enforcement flag with confidence. The six-phase path here gives you a repeatable process: observe first, validate in warn-only, rate limit in soft mode, add shadow auth, harden commands, narrow permissions last. Each phase has a concrete enforcement gate: flip the flag only when your warn-only logs show zero legitimate violations over the observation window.

If you want a faster path, run a SkillAudit scan first — the per-axis report tells you exactly which checks you're failing, so you can skip phases that are already clean and focus time on the actual gaps.

Related: MCP server input validation patterns · Rate limiting deep dive · DevSecOps CI/CD integration · Reject vs error