MCP Server Hardening: Close the Auth Gap Before an Auditor Does

// Failure mode: static client secret. The default pattern in most MCP tutorials.
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();

// One token check. No identity. 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;
  }
  // Failure 1: no user identity attached — every request looks identical in logs
  // Failure 2: secret never expires; rotation is a manual incident response
  // Failure 3: any client holding the secret has full tool access
  // Failure 4: the secret is already in someone's .env, probably in git
  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 middleware. JWT validated against the IdP — no static secrets.
import { createRemoteJWKSet, jwtVerify } from 'jose';
import type { Request, Response, NextFunction } from 'express';

interface UserContext {
  sub: string;        // stable user identifier from the IdP
  email: string;
  groups: string[];   // group claims — the basis for downstream authz
  scope: string;      // OAuth scopes — the basis for tool routing
}

// Carry verified context on the request. Tools trust this. Nothing else.
declare global {
  namespace Express {
    interface Request {
      user?: UserContext;
    }
  }
}

// JWKS cached by jose. Refreshes on key rotation. No manual handling.
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
    });

    // Verified context. Downstream tools read from req.user, not the request body.
    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) {
    // Real error to the log. Generic error to the caller.
    console.error('Token validation failed:', err instanceof Error ? err.message : err);

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

// Scope check per tool, not per request. Connection-level auth is not enough.
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. Verified user context flows through every tool call.
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import type { Request } from 'express';

// AsyncLocalStorage carries the context. No threading req through every function.
import { AsyncLocalStorage } from 'node:async_hooks';

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

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

// Seed the async store from the verified request. Tools read from the store.
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);
}

// One handler. Every tool pulls user context from the same 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. Downstream enforces 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) {
      // Structured error. Upstream response body never leaves this function.
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            error: 'upstream_error',
            status: response.status
            // Never include statusText or body — they leak internals.
          })
        }],
        isError: true
      };
    }

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

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

// Error sanitization. Internal context to the log. Generic codes to the caller.
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

// Internal code -> safe external code. Anything not in this map gets the default.
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'
  }
};

interface Logger {
  error(msg: string, ctx: Record<string, unknown>): void;
}

export function sanitizeError(
  err: unknown,
  toolName: string,
  userId: string,
  logger: Logger
): McpError {
  // The real error goes to the aggregator. Always.
  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 to the log. Never to the caller.
    stack: err instanceof Error ? err.stack : undefined
  });

  const safeError = SAFE_ERROR_CODES[errorCode];

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

  // Default: generic message, nothing internal in the wire response.
  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);
// }