From 79b8dbe221547f763305ebd82026f6bbdddd5ba8 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Thu, 20 Nov 2025 20:59:32 -0500 Subject: [PATCH] Document MCP tools loading issue in Claude Code (issue #346) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added Known Issues section to beads-mcp README documenting: - FastMCP schema generation bug blocking MCP tools in Claude Code - Workaround using slash commands (/beads:ready, /beads:show, etc.) - Links to issue #346 and upstream FastMCP issue #2455 - Resolution path once upstream fix is released 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- integrations/beads-mcp/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/integrations/beads-mcp/README.md b/integrations/beads-mcp/README.md index 555f95e0..0adb3389 100644 --- a/integrations/beads-mcp/README.md +++ b/integrations/beads-mcp/README.md @@ -222,6 +222,24 @@ await beads_ready_work(workspace_root="/Users/you/project-a") - `reopen` - Reopen a closed issue with optional reason - `set_context` - Set default workspace for subsequent calls (backward compatibility) +## Known Issues + +### MCP Tools Not Loading in Claude Code (Issue [#346](https://github.com/steveyegge/beads/issues/346)) + +**Status:** Blocked by upstream FastMCP bug ([#2455](https://github.com/jlowin/fastmcp/issues/2455)) + +MCP tools currently fail to load in Claude Code due to a schema generation bug in FastMCP 2.13.1. The issue affects self-referential Pydantic models and causes Claude Code to reject all beads MCP tools. + +**Workaround:** Use slash commands instead of MCP tools in Claude Code: +- `/beads:ready` instead of the `ready` MCP tool +- `/beads:show bd-123` instead of the `show` MCP tool +- `/beads:list` instead of the `list` MCP tool +- etc. + +Slash commands work because they call the `bd` CLI directly rather than going through the MCP tool interface. + +**Resolution:** This will be fixed automatically once FastMCP releases a fix for their schema generation bug. The beads-mcp dependency will then be updated to use the fixed version. + ## Development