Track: FastMCP 2.14.x outputSchema incompatibility with Claude Desktop

[phernandez]

Summary

FastMCP 2.14.x introduces automatic outputSchema generation for all MCP tools, but Claude Desktop doesn't support this field and disables the tool toggle entirely when it encounters it. This causes MCP tools to be invisible to users despite being registered correctly server-side.

Current Status

Fixed in v0.16.3 by pinning to fastmcp==2.12.3 (PR #464)

Root Cause

FastMCP 2.14.0 Breaking Change

FastMCP 2.14.0 removed the ability to disable outputSchema generation:

• output_schema=False was deprecated in 2.11.4
• Removed entirely in 2.14.0
• Now outputSchema is always generated for all tools

Claude Desktop Incompatibility

When Claude Desktop receives tool definitions with outputSchema:

• The tool toggle is disabled in the UI
• Tools appear registered server-side (tools/list returns all tools)
• But tools are not available in conversations
• Users see "tool not found" errors

Version Comparison

Package	Working	Broken
fastmcp	2.12.3	2.14.x
mcp	1.14.0	1.24.0

User Reports

From Discord (Dec 19, 2025):

Claude Desktop connects to Basic Memory successfully – I can see in the logs that tools/list returns all 18 tools – but Claude doesn't make them available in conversations. The MCP server shows "running" in settings.

Users confirmed:

• ✅ Server shows "running" in MCP settings
• ✅ Logs show successful initialize
• ✅ tools/list returns all 18 tools
• ✅ prompts/list and resources/list work
• ❌ Tools NEVER available in conversations

Upstream Issues

• FastMCP: jlowin/fastmcp#2654 - Request for global config to disable outputSchema
• Claude Code: anthropics/claude-code#10031 - Related outputSchema validation issue (fixed)
• Claude Code: anthropics/claude-code#14807 - Broader MCP breakage Dec 19, 2025

Troubleshooting for Users

If you're still experiencing issues after upgrading to v0.16.3:

1. Verify FastMCP Version

pip show fastmcp
# Should show Version: 2.12.3

2. Clean Reinstall

# Option 1: pip
pip uninstall basic-memory fastmcp -y
pip install basic-memory

# Option 2: uvx
uvx --reinstall basic-memory

# Option 3: pipx
pipx uninstall basic-memory
pipx install basic-memory

3. Restart Claude Desktop

Fully quit and restart Claude Desktop after reinstalling.

4. Windows Users

If still not working, try killing orphan Node processes:

Get-Process | Where-Object {$_.ProcessName -like "*node*"} | Stop-Process -Force

Resolution Path

This issue will remain open to track when we can safely upgrade FastMCP:

• FastMCP adds global config option to disable outputSchema (#2654)
• OR Claude Desktop adds support for outputSchema
• Test upgrade to newer FastMCP version
• Remove pin and update dependency

Related

• Pin FastMCP to 2.12.3 - Version 2.14.x breaks MCP tools visibility #463 - Original issue report
• fix: Pin FastMCP to 2.12.3 to fix MCP tools visibility #464 - PR that pinned FastMCP to 2.12.3

[claude]

Claude finished @phernandez's task in 1m 30s —— View job

---

Issue Triage Complete

• Read issue and classify type/priority/complexity
• Check for duplicate issues
• Add appropriate labels
• Provide triage summary

---

Triage Analysis

Issue Classification:

• Type: Tracking issue / Enhancement
• Priority: Medium
• Component: MCP tools, Dependencies
• Complexity: Medium (external dependency coordination)

Summary:
This is a well-documented tracking issue for monitoring the FastMCP outputSchema incompatibility. The immediate problem was already resolved in v0.16.3 by pinning to fastmcp==2.12.3 (PR #464). This issue serves as a reminder to upgrade once the upstream issues are resolved.

Duplicate Check:

• ✅ No duplicates found
• Related issue Pin FastMCP to 2.12.3 - Version 2.14.x breaks MCP tools visibility #463 is closed (the fix PR)
• Related issue Option to inline JSON Schema $defs for broader MCP client compatibility #444 dealt with a similar schema compatibility issue but was resolved differently

Key Points:

1. Current Status: Problem is fixed via dependency pinning
2. Root Cause: FastMCP 2.14.0 made outputSchema mandatory, but Claude Desktop doesn't support it
3. Resolution Path: Waiting for either:
   • FastMCP to add global config to disable outputSchema (jlowin/fastmcp#2654)
   • Claude Desktop to add outputSchema support
4. User Impact: Users on v0.16.3+ should not experience this issue

Recommendations:

• Keep this issue open as a tracking issue
• Monitor upstream FastMCP and Claude Desktop developments
• Consider adding this to a "blocked by external dependency" milestone if one exists
• The comprehensive troubleshooting guide in the issue body is valuable for users who may still encounter problems

Label Applied:

• enhancement - This tracks when we can enhance the codebase by upgrading to newer FastMCP versions