ajv v8 incompatible with Cloudflare Workers - SDK v1.21.0+ breaks integration tests #25
Description
The MCP SDK versions ≥1.21.0 are incompatible with Cloudflare Workers due to the upgrade from ajv@6.12.6 to ajv@8.17.1. This breaks integration tests and runtime execution in Workers environments.
Impact
- ❌ Cannot upgrade SDK from v1.20.2 to v1.21.0+
- ❌ Integration tests fail in Cloudflare Workers environment
- ❌ Runtime execution fails with SyntaxError
- ✅ SDK v1.20.2 and below work fine
Environment
{
"node": "v22.11.0",
"npm": "11.6.2",
"@modelcontextprotocol/sdk": "1.22.0",
"@cloudflare/vitest-pool-workers": "0.10.9",
"wrangler": "4.49.1",
"vitest": "3.2.4",
"compatibility_date": "2025-03-10",
"compatibility_flags": ["nodejs_compat"]
}
Steps to Reproduce
- Update deps for MCP SDK and agents libs
package.json:
{
"dependencies": {
"@modelcontextprotocol/sdk": "^1.22.0",
"agents": "^0.2.23"
},
"devDependencies": {
"@cloudflare/vitest-pool-workers": "^0.10.9",
"vitest": "^3.2.4"
}
}
- Run integration tests
npm run test:integration
Expected Behavior
Tests should pass successfully, as they do with SDK v1.20.2:
✓ test/integration/mcp-tools.test.ts (11 tests) 256ms
✓ test/integration/oauth-flow.test.ts (12 tests) 74ms
Test Files 2 passed (2)
Tests 23 passed (23)
Actual Behavior
Tests fail with SyntaxError:
⎯⎯⎯⎯⎯⎯ Failed Suites 2 ⎯⎯⎯⎯⎯⎯⎯
FAIL test/integration/mcp-tools.test.ts
FAIL test/integration/oauth-flow.test.ts
SyntaxError: The requested module 'ajv' does not provide an export named 'Ajv'
Root Cause Analysis
- ajv Version Change
| SDK Version | ajv Version | Import Syntax | Workers Compatible |
|---|---|---|---|
| ≤ 1.20.2 | 6.12.6 | import Ajv from 'ajv' | ✅ Yes |
| ≥ 1.21.0 | 8.17.1 | import { Ajv } from 'ajv' | ❌ No |
- Cloudflare Workers Limitations
ajv uses dynamic code generation (new Function(), eval()) which Cloudflare Workers restricts for security:
- ajv v6: Vite SSR optimizer successfully bundles it for Workers ✅
- ajv v8: Different ESM module structure breaks Vite bundling ❌
Related ajv issues:
- Allow it to work on edge (e.g. cloudflare workers) ajv-validator/ajv#2318
- Allow it to work on edge (e.g. cloudflare workers) ajv-validator/ajv#2491
- Package Override Doesn't Work
Attempting to override ajv version fails because SDK v1.22.0 uses ajv v8 API:
{
"overrides": {
"ajv": "6.12.6" // ❌ Doesn't work - SDK code expects v8 API
}
}
Workaround (Temporary)
Pin to SDK v1.20.2 and agents v0.2.21:
{
"dependencies": {
"@modelcontextprotocol/sdk": "1.20.2",
"agents": "0.2.21"
}
}
Additional Context
Version Compatibility Matrix
| MCP SDK | agents | ajv | Works in Workers? |
|---|---|---|---|
| 1.18.2 | 0.2.6 | 6.12.6 | ✅ Yes |
| 1.20.2 | 0.2.21 | 6.12.6 | ✅ Yes |
| 1.21.0 | 0.2.22 | 8.17.1 | ❌ No |
| 1.22.0 | 0.2.23 | 8.17.1 | ❌ No |
Related Dependencies
The issue also affects:
- zod-to-json-schema@3.25.0 (has ajv v8 in devDependencies)
- ajv-formats@3.0.1 (requires ajv v8)
Testing Environment
Using @cloudflare/vitest-pool-workers for integration testing with:
- Miniflare (local Workers runtime)
- SSR dependency optimization
- nodejs_compat compatibility flag
References