Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix Tool calls to MCP servers using draft-2020-12 JSON schemas fail with "no schema with key or ref" [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#70196•Fetched 2026-04-23 07:27:58
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Author
aaronedenaaroneden
Participants
aaronedenaaroneden

When openclaw's gateway hosts an MCP server whose tool schemas declare $schema: "https://json-schema.org/draft/2020-12/schema" (as @playwright/mcp does), every tool call fails at openclaw's validation layer with:

no schema with key or ref "https://json-schema.org/draft/2020-12/schema"

Tool discovery succeeds (the tools appear to agents), but every invocation fails before reaching the MCP server.

Error Message

Tool invocation fails with the schema error above. Reproduced with playwright-mcp @latest (0.0.70) and 0.0.69.

Root Cause

Root cause (likely)

PR fix notes

PR #71036: fix(mcp): add Ajv 2020-12 meta-schema support for external MCP server tools

Description (problem / solution / changelog)

Problem

External MCP servers (e.g. @playwright/mcp >= 0.0.28) declare tool inputSchemas using JSON Schema draft-2020-12. The existing Ajv draft-07 instance throws:

no schema with key or ref "https://json-schema.org/draft/2020-12/schema"

This makes all tools from draft-2020-12 MCP servers silently fail to initialize.

Closes #68772, #70196

Fix

In src/plugins/schema-validator.ts:

  • Detect $schema === 'https://json-schema.org/draft/2020-12/schema' on incoming schemas
  • Route those to an Ajv2020 instance loaded from ajv/dist/2020 (already a transitive dep)
  • Keep the existing draft-07 path for all other schemas
  • Both paths share the same singleton map and uri format override

No new dependencies — ajv/dist/2020 is a subpath of the already-installed ajv package.

Tests

Added 5 new test cases in src/plugins/schema-validator.test.ts:

  • draft-2020-12 schema validates correctly
  • draft-2020-12 schema rejects invalid values with proper errors
  • draft-07 schemas continue to work unchanged
  • mixed usage works (both variants active simultaneously)
  • schemas without $schema default to draft-07

All 14 tests pass (pnpm test:fast).

AI-assisted

  • AI-assisted (Claude Code via OpenClaw)
  • Lightly tested: pnpm test:fast targeting schema-validator.test.ts — 14/14 passed
  • I understand what the code does
  • Focused PR: only touches src/plugins/schema-validator.ts and its test file

Changed files

  • src/plugins/schema-validator.test.ts (modified, +53/-0)
  • src/plugins/schema-validator.ts (modified, +30/-10)

Code Example

no schema with key or ref "https://json-schema.org/draft/2020-12/schema"

---

openclaw mcp set playwright '{"command":"bash","args":["-c","cd /tmp && exec npx @playwright/mcp@latest --browser chrome"]}'
openclaw gateway restart
openclaw agent --agent main --message "Call playwright__browser_navigate url=https://example.com then playwright__browser_snapshot." --thinking low
RAW_BUFFERClick to expand / collapse

Summary

When openclaw's gateway hosts an MCP server whose tool schemas declare $schema: "https://json-schema.org/draft/2020-12/schema" (as @playwright/mcp does), every tool call fails at openclaw's validation layer with:

no schema with key or ref "https://json-schema.org/draft/2020-12/schema"

Tool discovery succeeds (the tools appear to agents), but every invocation fails before reaching the MCP server.

Environment

  • OpenClaw 2026.4.21 (f788c88), beta channel
  • macOS 15, Node 25.8.2 (pinned at ~/.openclaw/runtime/node/bin/node)
  • Model path: openai-codex/gpt-5.4 via OAuth

Reproduction

openclaw mcp set playwright '{"command":"bash","args":["-c","cd /tmp && exec npx @playwright/mcp@latest --browser chrome"]}'
openclaw gateway restart
openclaw agent --agent main --message "Call playwright__browser_navigate url=https://example.com then playwright__browser_snapshot." --thinking low

Tool invocation fails with the schema error above. Reproduced with playwright-mcp @latest (0.0.70) and 0.0.69.

Root cause (likely)

package.json depends on ajv ^8.18.0. AJV 8 only supports draft-07 by default; it needs the Ajv2020 entry point (import Ajv2020 from "ajv/dist/2020") or explicit addMetaSchema(draft2020) to accept draft-2020-12 schemas. The MCP SDK / Zod v4 emits draft-2020-12 $schema by default — so any modern MCP server is affected.

Suggested fix

Swap the validator for new Ajv2020(...) in whatever module validates tool schemas, or call ajv.addMetaSchema(require("ajv/dist/refs/json-schema-2020-12.json")) at startup.

Impact

Blocks any modern MCP server (playwright-mcp, chrome-devtools-mcp, and most Zod-v4-generated servers). Forces users onto openclaw's built-in browser automation ("Nodes"), which has its own reliability issues (open -a Google Chrome <node-hash> failures).

extent analysis

TL;DR

Update the validation module to use Ajv2020 or add the draft-2020-12 meta schema to support modern MCP servers.

Guidance

  • Identify the module responsible for validating tool schemas and update it to use Ajv2020 instead of the default Ajv to support draft-2020-12 schemas.
  • Alternatively, add the draft-2020-12 meta schema to the existing ajv instance using ajv.addMetaSchema(require("ajv/dist/refs/json-schema-2020-12.json")) at startup.
  • Verify that the fix works by reproducing the issue with the updated validation module and checking that tool invocations succeed.
  • Consider updating the package.json dependency on ajv to ensure that future updates do not reintroduce the issue.

Example

// Before
const Ajv = require('ajv');
const ajv = new Ajv();

// After
const Ajv2020 = require('ajv/dist/2020');
const ajv = new Ajv2020();

or

const Ajv = require('ajv');
const ajv = new Ajv();
ajv.addMetaSchema(require("ajv/dist/refs/json-schema-2020-12.json"));

Notes

The suggested fix assumes that the issue is caused by the outdated ajv version used in the validation module. If the issue persists after applying the fix, further investigation may be needed to identify the root cause.

Recommendation

Apply the workaround by updating the validation module to use Ajv2020 or adding the draft-2020-12 meta schema, as this is a more targeted solution that addresses the specific issue at hand.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#request timeout

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix Tool calls to MCP servers using draft-2020-12 JSON schemas fail with "no schema with key or ref" [1 pull requests, 1 participants]