Fix the Zod handshake bug — build a Notion-ready MCP server in 60 lines

Why .strip() or .passthrough() alone won't save you

The 6-line fix

// Place this BEFORE app.post('/mcp', ...)
const NOTION_EXTRA_FIELDS = ['nonce', 'notion_user_id', 'prompt'] as const;

function notionStripMiddleware(req: Request, _res: Response, next: Function) {
  if (req.body && typeof req.body === 'object') {
    for (const field of NOTION_EXTRA_FIELDS) {
      delete (req.body as Record<string, unknown>)[field];
    }
  }
  next();
}

Complete copy-pasteable server

// server.ts — Notion-compatible MCP server
import { createMcpExpressApp } from '@modelcontextprotocol/express';
import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
import { McpServer } from '@modelcontextprotocol/server';
import type { Request, Response } from 'express';
import * as z from 'zod/v4';

// ── 1. The middleware ──────────────────────────────────────────────────────
const NOTION_EXTRA_FIELDS = ['nonce', 'notion_user_id', 'prompt'] as const;

function notionStripMiddleware(req: Request, _res: Response, next: Function) {
  if (req.body && typeof req.body === 'object') {
    const body = req.body as Record<string, unknown>;
    const stripped = NOTION_EXTRA_FIELDS.filter(f => f in body);
    if (stripped.length) {
      console.log('[notionStrip] removed:', stripped.join(', '));
      for (const field of stripped) delete body[field];
    }
  }
  next();
}

// ── 2. Tool definition ─────────────────────────────────────────────────────
function createServer(): McpServer {
  const server = new McpServer(
    { name: 'pm-dashboard', version: '1.0.0' },
    { capabilities: { logging: {} } }
  );

server.registerTool(
    'query-dashboard',
    {
      title: 'Query Dashboard',
      description: 'Fetch key product metrics',
      inputSchema: z.object({
        metric: z.enum(['dau', 'mau', 'revenue', 'retention', 'nps']),
        period: z.enum(['7d', '30d', '90d']).default('7d'),
      }),
    },
    async ({ metric, period }) => {
      // Replace with your real data source
      const data: Record<string, { value: number; change: number }> = {
        dau: { value: 482000, change: 3.2 },
        mau: { value: 2800000, change: 1.8 },
        revenue: { value: 12400000, change: -0.5 },
        retention: { value: 62.4, change: 0.3 },
        nps: { value: 47, change: 2.1 },
      };
      const d = data[metric] ?? { value: 0, change: 0 };
      return {
        content: [{
          type: 'text',
          text: `${metric.toUpperCase()} (${period}): ${d.value} (${d.change > 0 ? '+' : ''}${d.change}%)`,
        }],
      };
    }
  );

return server;
}

// ── 3. Express wiring ──────────────────────────────────────────────────────
const app = createMcpExpressApp();

app.post('/mcp', notionStripMiddleware, async (req: Request, res: Response) => {
  const server = createServer();
  try {
    const transport = new NodeStreamableHTTPServerTransport({
      sessionIdGenerator: undefined, // stateless — required for Notion
    });
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
    res.on('close', () => { transport.close(); server.close(); });
  } catch (err) {
    console.error('MCP error:', err);
    if (!res.headersSent) {
      res.status(500).json({
        jsonrpc: '2.0',
        error: { code: -32603, message: 'Internal server error' },
        id: null,
      });
    }
  }
});

// GET /mcp — Notion probes this; return 405 for stateless servers
app.get('/mcp', (_req: Request, res: Response) => {
  res.writeHead(405).end(JSON.stringify({
    jsonrpc: '2.0',
    error: { code: -32000, message: 'Use POST.' },
    id: null,
  }));
});

const PORT = parseInt(process.env.PORT ?? '3000', 10);
app.listen(PORT, () => console.log(`MCP server on http://localhost:${PORT}/mcp`));
process.on('SIGINT', () => process.exit(0));

// package.json
{
  "name": "notion-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "scripts": { "start": "tsx server.ts", "dev": "tsx watch server.ts" },
  "dependencies": {
    "@modelcontextprotocol/express": "^2.0.0-alpha.2",
    "@modelcontextprotocol/node": "^2.0.0-alpha.2",
    "@modelcontextprotocol/server": "^2.0.0-alpha.2",
    "express": "^4.21.0",
    "zod": "^4.0.0"
  },
  "devDependencies": { "tsx": "^4.16.0", "typescript": "^5.9.0" }
}

Deploying and connecting to Notion

Verifying it worked

1. Tool enumeration: Expand the MCP connection entry in the agent's settings. If query-dashboard appears in the tool list, the handshake completed — the middleware worked.
2. Log confirmation: Your server console should show [notionStrip] removed: nonce, notion_user_id, prompt on the first request. If that line appears, the three fields were present and stripped correctly.

4 gotchas specific to this setup