How to Harden Your MCP Server Before It Becomes a Security Incident

// DANGER: Static client secret — what most MCP servers look like today
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
import express from 'express';

const STATIC_SECRET = process.env.MCP_SECRET ?? 'my-hardcoded-secret-123';

const app = express();

// Middleware: single static token check — no user context, no expiry, no rotation
app.use((req, res, next) => {
  const auth = req.headers['authorization'];
  if (auth !== `Bearer ${STATIC_SECRET}`) {
    res.status(401).json({ error: 'Unauthorized' });
    return;
  }
  // Problem 1: No user identity attached — all requests look identical
  // Problem 2: Secret never expires, rotates only on manual intervention
  // Problem 3: Any client with the secret has full tool access
  // Problem 4: Secret likely lives in a .env committed to git at some point
  next();
});

const server = new Server(
  { name: 'internal-tools', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

app.get('/sse', async (req, res) => {
  const transport = new SSEServerTransport('/message', res);
  await server.connect(transport);
});

app.listen(3000);

// MCP server with OIDC JWT validation — no static secrets
import { createRemoteJWKSet, jwtVerify } from 'jose';
import type { Request, Response, NextFunction } from 'express';

interface UserContext {
  sub: string;        // stable user identifier
  email: string;
  groups: string[];   // from IdP group claims
  scope: string;      // granted OAuth scopes
}

// Extend Express request to carry verified user context
declare global {
  namespace Express {
    interface Request {
      user?: UserContext;
    }
  }
}

// Load JWKS from your IdP — cached automatically by jose, refreshes on rotation
const JWKS = createRemoteJWKSet(
  new URL(process.env.OIDC_JWKS_URI!) // e.g. https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys
);

export async function requireAuth(
  req: Request,
  res: Response,
  next: NextFunction
): Promise<void> {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith('Bearer ')) {
    res.status(401).json({
      error: 'missing_token',
      error_description: 'Authorization header with Bearer token required'
    });
    return;
  }

  const token = authHeader.slice(7);

  try {
    const { payload } = await jwtVerify(token, JWKS, {
      issuer: process.env.OIDC_ISSUER,   // e.g. https://login.microsoftonline.com/{tenant}/v2.0
      audience: process.env.OIDC_AUDIENCE // your MCP server's registered client ID
    });

    // Attach verified user context — downstream tools can trust this
    req.user = {
      sub: payload.sub as string,
      email: payload.email as string,
      groups: (payload.groups as string[]) ?? [],
      scope: (payload.scp ?? payload.scope ?? '') as string
    };

    next();
  } catch (err: unknown) {
    // Log the real error internally, return generic message to caller
    console.error('Token validation failed:', err instanceof Error ? err.message : err);

    res.status(401).json({
      error: 'invalid_token',
      error_description: 'Token validation failed'
      // Note: never forward err.message — it can expose IdP internals
    });
  }
}

// Scope enforcement — call this per-tool, not per-request
export function requireScope(requiredScope: string) {
  return (req: Request, res: Response, next: NextFunction): void => {
    const grantedScopes = req.user?.scope?.split(' ') ?? [];
    if (!grantedScopes.includes(requiredScope)) {
      res.status(403).json({
        error: 'insufficient_scope',
        error_description: `Required scope: ${requiredScope}`
      });
      return;
    }
    next();
  };
}

// Identity propagation — passing user context through MCP tool execution
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import type { Request } from 'express';

// Async context carrier — avoids threading req through every function
import { AsyncLocalStorage } from 'node:async_hooks';

interface RequestContext {
  userId: string;
  userEmail: string;
  userGroups: string[];
  originalToken: string; // forward to downstream services that accept it
}

export const requestContext = new AsyncLocalStorage<RequestContext>();

// In your SSE handler, seed the async context from the verified request
export function withUserContext<T>(req: Request, fn: () => Promise<T>): Promise<T> {
  const ctx: RequestContext = {
    userId: req.user!.sub,
    userEmail: req.user!.email,
    userGroups: req.user!.groups,
    originalToken: req.headers.authorization!.slice(7)
  };
  return requestContext.run(ctx, fn);
}

// Tool registration — each tool pulls user context from the store
const server = new Server(
  { name: 'internal-tools', version: '2.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const ctx = requestContext.getStore();
  if (!ctx) {
    throw new Error('No request context — tool called outside authenticated scope');
  }

  const { name, arguments: args } = request.params;

  if (name === 'query-customer-data') {
    // Forward the user's own token to the downstream API
    // The downstream service enforces its own row-level access
    const response = await fetch('https://internal-api.example.com/customers', {
      headers: {
        'Authorization': `Bearer ${ctx.originalToken}`,
        'X-Forwarded-User': ctx.userId,
        'X-Forwarded-Email': ctx.userEmail
      }
    });

    if (!response.ok) {
      // Return structured error — do not expose upstream response body
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            error: 'upstream_error',
            status: response.status
            // Note: never include response.statusText or body — they can leak internals
          })
        }],
        isError: true
      };
    }

    const data = await response.json();
    return {
      content: [{ type: 'text', text: JSON.stringify(data) }]
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// Structured error handling — safe for production MCP servers
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

// Error category map — internal codes map to safe external codes
const SAFE_ERROR_CODES: Record<string, { code: ErrorCode; message: string }> = {
  'ECONNREFUSED': {
    code: ErrorCode.InternalError,
    message: 'Upstream service unavailable'
  },
  'ETIMEDOUT': {
    code: ErrorCode.InternalError,
    message: 'Request timed out'
  },
  'INVALID_GRANT': {
    code: ErrorCode.InvalidRequest,
    message: 'Authentication token is no longer valid'
  },
  'PERMISSION_DENIED': {
    code: ErrorCode.InvalidRequest,
    message: 'Insufficient permissions for this operation'
  }
};

// Logger interface — replace with your production logger
interface Logger {
  error(msg: string, ctx: Record<string, unknown>): void;
}

export function sanitizeError(
  err: unknown,
  toolName: string,
  userId: string,
  logger: Logger
): McpError {
  // Log the real error internally — include context for debugging
  const internalMessage = err instanceof Error ? err.message : String(err);
  const errorCode = (err as NodeJS.ErrnoException).code ?? 'UNKNOWN';

  logger.error('Tool execution error', {
    tool: toolName,
    userId,
    errorCode,
    // Stack trace goes to your log aggregator, never to the caller
    stack: err instanceof Error ? err.stack : undefined
  });

  // Map to safe external error
  const safeError = SAFE_ERROR_CODES[errorCode];

  if (safeError) {
    return new McpError(safeError.code, safeError.message);
  }

  // Default: return generic message for anything unrecognized
  // Do NOT include internalMessage in the returned error
  return new McpError(
    ErrorCode.InternalError,
    'An unexpected error occurred. Reference your support team with the request timestamp.'
  );
}

// Usage in a tool handler:
// try {
//   const result = await callDownstreamService(args);
//   return { content: [{ type: 'text', text: JSON.stringify(result) }] };
// } catch (err) {
//   throw sanitizeError(err, 'tool-name', ctx.userId, logger);
// }