Deepseek and MCPs ($ref/$defs in MCP tool schemas causes AttributeError)

[meerestier]

Description

Title: DeepSeek provider: $ref/$defs in MCP tool schemas causes AttributeError
Description:
Version: opencode 1.17.5
Provider: DeepSeek
Affected MCP servers: Asana (mcp.asana.com/v2/mcp), Notion (@notionhq/notion-mcp-server)

Error:
Error from provider: Error resolving schema reference '#/$defs/richTextRequest': AttributeError("'NoneType' object has no attribute 'lookup'")
Possible cause: MCP servers output valid JSON Schema 2020-12 with $ref → $defs references. DeepSeek's API (like Fireworks, Anthropic, Gemini) strictly validates schemas and rejects unresolved $ref pointers. The same error occurs with Notion MCP (#/properties/sections/items/properties/tasks/items/properties/assignee).
Expected fix: opencode should dereference/flatten $ref before sending to DeepSeek — similar to the Gemini sanitization done in #12292.
Workaround: Disable affected MCP servers or switch to a provider that handles $ref natively (e.g. OpenAI).
References:

• LiteLLM feat(scout): materialize configured reference repos #26692 — identical error with Fireworks
• opencode fix: expand $ref references in JSON Schema for Gemini compatibility #12292 / Gemini API rejects JSON Schema containing $ref references #12295 — Gemini fix for same class of problem
• FastMCP fix: checksum error with glamour and x/ansi. #2808 — schema dereferencing for MCP client compatibility

Plugins

No response

OpenCode version

1.17.5

Steps to reproduce

{
"$schema": "https://opencode.ai/config.json",
"small_model": "google/gemini-3-flash-preview",
"mcp": {
"asana": {
"type": "remote",
"url": "https://mcp.asana.com/v2/mcp",
"oauth": {
"clientId": "{env:ASANA_MCP_CLIENT_ID}",
"clientSecret": "{env:ASANA_MCP_CLIENT_SECRET}"
}
},
"chrome-devtools": {
"type": "local",
"command": ["npx", "-y", "chrome-devtools-mcp@latest"]
},
"figma": {
"type": "local",
"command": ["npx", "-y", "figma-mcp"]
},
"notion-sys": {
"type": "local",
"command": ["npx", "-y", "@notionhq/notion-mcp-server"],
"environment": {
"NOTION_TOKEN": "xyz"
}
},
"notion-lv": {
"type": "local",
"command": ["npx", "-y", "@notionhq/notion-mcp-server"],
"environment": {
"NOTION_TOKEN": "xyz"
}
}
}
}

Screenshot and/or share link

No response

Operating System

macOS 26.4.1

Terminal

Nova, System bash

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Error resolving schema reference '$ref' in Canva MCP tool when using custom API provider #29220: Same AttributeError when resolving $ref in MCP tool schemas with a custom/Fireworks API provider (same error message, same root cause)
• MCP tools fail to load when outputSchema contains unresolved refs #26529: MCP tools failing to load due to unresolved $ref/$defs in outputSchema (same schema dereferencing class of problem)

If your issue is distinct (e.g., specific to the DeepSeek provider path rather than the schema resolution layer), please add clarification so maintainers can differentiate.

[lexlian]

@meerestier @StarpTech ,I fixed the issue with PR #32955.

Root cause: DeepSeek API rejects JSON Schema 2020-12 $ref pointers in MCP tool schemas. ProviderTransform.schema() had sanitization for Moonshot/Kimi and Google/Gemini but no branch for DeepSeek — unresolved $ref pointers were passed through directly, causing AttributeError: 'NoneType' object has no attribute 'lookup'.

The fix: Added expandRefs() that inlines $ref targets from $defs/definitions before sending schemas to DeepSeek. Handles nested refs, preserves override fields on referencing nodes, and guards against circular refs via a seen set.

Also closes #29220 (duplicate: same error with Fireworks + Canva MCP).

[devguimaraes]

Same issue here, but with Moonshot AI (Kimi K2.7) + Sanity MCP.

Exact error:

Error from provider (Moonshot AI): Invalid request: tools.function.parameters is not a valid moonshot flavored json schema, details: <At path 'properties.documents.additionalProperties.properties.patches.items.properties.insert.anyOf.properties.items.$ref': references must start with #/$defs/>

Offending tool: sanity_patch_documents — the schema uses internal $ref with relative paths (#/properties/...) instead of #/$defs/..., which Moonshot's validator rejects.

Environment:

• opencode CLI (TUI) on Linux
• Provider: Moonshot AI (kimi-k2.7)
• MCP servers: Sanity, Linear, Stitch, Context7
• Sanity MCP: https://mcp.sanity.io (remote)

Applied workaround: disabling Sanity MCP ("enabled": false) fixes it, but loses access to CMS tools.

Root cause is the same: opencode sends raw JSON schema from MCP tools without dereferencing/resolving $ref before forwarding to providers with strict validators (Moonshot, DeepSeek, Gemini). The fix from PR #12292 for Gemini could serve as a template for other providers.

[github-actions]

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.