Claude Code: FastMCP Bug Blocks Beads MCP Tools
Discover why your Beads MCP tools aren't loading in Claude Code and what's causing the frustrating invalid_literal error. If you've recently tried to access your Beads MCP tools within the Claude Code environment, you might have encountered a rather baffling issue: everything seems to connect just fine, but when it comes to actually using the tools, they simply refuse to load. This isn't a problem with Beads itself, nor is it an issue with Claude Code's fundamental functionality. Instead, the culprit lies within the FastMCP output schema generation, specifically a bug present in version 2.13.1. This bug prevents Claude Code, a meticulous MCP client, from validating the schema provided by the Beads MCP server, leading to a cascade of errors that render the tools inaccessible. While this might sound technical, understanding the root cause is the first step toward a resolution. We'll dive deep into the error messages, explain the technical nitty-gritty of the schema validation, and most importantly, guide you through the current workarounds and the path to a permanent fix. So, if your workflow has been disrupted by this unexpected roadblock, stick around – we're here to help you navigate through it.
Understanding the invalid_literal Error in Beads MCP
Let's get straight to the heart of the problem: the invalid_literal error that appears when your Beads MCP tools fail to load in Claude Code. This specific error message, often found deep within your Claude Code debug logs (typically located in ~/.claude/debug/*.txt), points directly to a schema validation failure. The log snippet "code": "invalid_literal", "expected": "object", "path": ["tools", 4, "outputSchema", "type"], "message": "Invalid literal value, expected \"object\"" is your primary clue. It tells us that at a specific point in the schema definition – namely, the type property within an outputSchema located at tools[4] – the system was expecting the value "object", but it received something else. This is crucial because, according to the Message Communication Protocol (MCP) specification, the outputSchema for any tool must be defined as an object. Claude Code, as a compliant MCP client, rigorously enforces this rule. When it receives a schema that deviates from this requirement, even if it's a subtle deviation, it refuses to process the tools, effectively blocking them. It's important to note that this doesn't mean the MCP server connection itself is broken, nor does it halt other functionalities like slash commands. The server connects, resources like beads://quickstart load without a hitch, and even the basic slash commands still function as expected. The issue is precisely confined to the parsing and validation of the tool definitions provided by the Beads MCP server, a problem stemming from how FastMCP generates these definitions. This distinction is vital because it helps us pinpoint the exact layer where the malfunction occurs, guiding our troubleshooting efforts toward the correct component.
The Root Cause: A FastMCP Schema Generation Bug
The primary reason your Beads MCP tools are failing to load in Claude Code boils down to a specific bug within the FastMCP library, version 2.13.1, to be precise. It's crucial to understand that the Beads plugin itself, and its implementation of MCP tools, is functioning correctly. The issue arises during the process where FastMCP automatically generates the JSON schema definitions for the outputSchema of your tools. Many tools within the Beads ecosystem, such as show, ready, and list, are designed to return Issue objects. These Issue objects have a self-referential structure, meaning they can contain references to other Issue objects through fields like dependencies and dependents. When FastMCP encounters these self-referential Pydantic models, it generates schemas that utilize $ref directives to point to the definition of the Issue model itself. The problematic part is that, in certain cases, FastMCP generates these schemas with the $ref at the root level without explicitly including the required `
