Option to inline JSON Schema $defs for broader MCP client compatibility

[johnlindquist]

Description

basic-memory's MCP server uses FastMCP which generates JSON Schemas with $defs references. Some MCP clients (like code-mode/UTCP) cannot resolve these references, causing tool discovery to fail.

Error (from code-mode client)

MissingRefError: can't resolve reference #/$defs/ContextResult from id #

Context

This is part of a broader MCP ecosystem issue where different clients expect different JSON Schema drafts:

• MCP TypeScript SDK generates JSON Schema draft-07, breaking compatibility with modern MCP clients requiring draft-2020-12 modelcontextprotocol/typescript-sdk#745
• SEP-834 Support full JSON Schema 2020-12 modelcontextprotocol/modelcontextprotocol#834

Feature Request

Would it be possible to add an option or configuration to inline/dereference $defs in the tool schemas? This would improve compatibility with MCP clients that don't support $defs resolution.

Alternatively, if FastMCP provides a way to configure schema generation, that could be exposed.

Environment

• basic-memory: 0.15.2
• FastMCP: 2.12.4
• MCP SDK: 1.17.0

[phernandez]

@claude this seems like something that would be required in the mcp sdk or fastmcp.

[claude]

Claude finished @phernandez's task —— View job

---

Analysis Complete

• Read project documentation and understand FastMCP integration
• Examine MCP tool definitions and schema generation
• Analyze where the fix should be implemented
• Provide technical recommendation

---

Response

You're absolutely right that this is an upstream issue, not something that should be fixed in basic-memory itself. Here's my analysis:

Where the issue belongs:

1. FastMCP - This is where schema generation happens. FastMCP uses Pydantic models to automatically generate JSON schemas for MCP tools via the @mcp.tool() decorator. The $defs references are created by Pydantic's JSON schema generation.

2. MCP SDK/Spec - The broader issue is that the MCP specification doesn't mandate a specific JSON Schema draft version, leading to different clients having different expectations about schema features like $defs.

Why basic-memory shouldn't fix this:

1. Abstraction layer violation - basic-memory uses FastMCP as a high-level abstraction. All tool definitions use @mcp.tool() decorators and have no direct control over schema generation (see src/basic_memory/mcp/tools/*.py).

2. No configuration surface - basic-memory's MCP server is intentionally minimal (src/basic_memory/mcp/server.py:7-9):

   mcp = FastMCP(name="Basic Memory")

   There's no schema configuration being passed to FastMCP.

3. Ecosystem-wide problem - As the linked issues show, this affects multiple MCP servers and clients. A workaround in basic-memory wouldn't solve the underlying compatibility problem.

Recommended path forward:

1. Open an issue with FastMCP (https://github.com/jlowin/fastmcp) to request an option for inlining $defs or generating JSON Schema Draft 2019-09 compatible schemas
2. Contribute to the MCP spec discussion in the linked issues to help establish clearer schema compatibility requirements
3. For immediate workaround: Users experiencing this with code-mode/UTCP could potentially use a different MCP client that supports $defs resolution until upstream fixes are available

The good news is that this is a known issue in the MCP ecosystem and is being actively discussed. A fix at the FastMCP or MCP SDK level would benefit all servers and clients, not just basic-memory.

---

[johnlindquist]

@phernandez Sorry about this, I was investigating integrating "code mode" with basic-memory and Opus 4.5 started creating issues without being prompted too (it's my fault since I was running in yolo mode).

Although the end results of your CI Claude research dismissing my local Claude research does tickle my funny bone.