MCP Server Invalid JSON Schema Breaks Claude Desktop

Oct 25, 2025 by SLV Team 53 views

MCP Server: Invalid inputSchema Breaks Claude Desktop Compatibility

Hey guys! Let's dive into a critical issue affecting the compatibility of the Twenty MCP server with MCP clients like Claude Desktop. This article will break down the problem, its impact, and the required fix. We're talking about how an incorrectly formatted inputSchema is causing major headaches, so stick around!

Description

The Twenty MCP server hosted at twenty.brainblendai.com/mcp is currently serving tool definitions with an inputSchema that's not quite up to spec. Specifically, it includes an extra jsonSchema wrapper. According to the MCP specification, this is a no-no, and it's preventing tools from being correctly recognized by MCP clients, most notably Claude Desktop. This means that users aren't seeing the full functionality they should, and that's never a good thing.

The core of the problem lies in the format of the inputSchema. The server is wrapping the actual JSON Schema within another layer, which is unnecessary and breaks compatibility. Let's take a closer look at what's happening and how it should be.

The current, incorrect format looks something like this:

{
 "name": "create_company",
 "description": "...",
 "inputSchema": {
 "jsonSchema": {
 "type": "object",
 "properties": {...}
 }
 }
}

Notice the extra jsonSchema wrapper? That's the culprit! It's like putting a gift inside another box – unnecessary and confusing for the recipient.

Now, let's contrast that with the expected, correct format as per the MCP specification. The inputSchema should directly contain the JSON Schema, without any extra layers:

{
 "name": "create_company",
 "description": "...",
 "inputSchema": {
 "type": "object",
 "properties": {...}
 }
}

See the difference? Much cleaner, right? This is how MCP clients expect the data to be structured, and when it's not, things start to break. This deviation from the specification is the root cause of the compatibility issues we're seeing.

Reproduction

Want to see this issue in action? You can easily reproduce it yourself using curl. Just fire up your terminal and use the following command:

curl -X POST https://twenty.brainblendai.com/mcp   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -H "MCP-Protocol-Version: 2025-06-18"   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Make sure to replace YOUR_TOKEN with your actual authorization token. This command sends a request to the MCP server to list the available tools. When you inspect the response, you'll see the incorrectly formatted inputSchema with the extra jsonSchema wrapper. This is concrete evidence of the issue and a great way to confirm that you're experiencing the same problem.

By running this command, you can directly observe the server's response and verify the presence of the extra jsonSchema wrapper. This hands-on approach is super helpful for understanding the problem and demonstrating its existence to others. Plus, it's always good to get your hands dirty with a little command-line action!

Impact

The impact of this seemingly small formatting issue is actually quite significant. Let's break down the key consequences:

Claude Desktop Can't Recognize Tools: This is the big one. Because of the incorrect inputSchema format, Claude Desktop simply ignores the tools provided by the MCP server. They are silently dropped, which means users are missing out on a whole range of functionalities. Imagine having a toolbox full of awesome tools, but your software can't even see them – frustrating, right?
Other MCP Clients May Fail: Claude Desktop isn't the only client affected. Any MCP client that strictly adheres to the specification will also struggle to load tools from the server. This limits the interoperability of the server and makes it difficult to integrate with other applications and services. We want our systems to play nicely together, and this issue is preventing that.
Empty Tools List for Users: Ultimately, the end-users are the ones who suffer. They see an empty tools list, even though the server is actually returning a healthy number of tools (30+ in this case). This leads to a poor user experience and can create confusion and frustration. Users might think there's a problem with the server or the client, when the real issue is the formatting of the inputSchema.

In essence, this issue undermines the entire purpose of the MCP, which is to provide a standardized way for tools to be discovered and used across different platforms. By violating the specification, the server is creating a barrier to integration and limiting the usefulness of its tools. We need to fix this to ensure a smooth and consistent experience for everyone.

Environment

To give you the full picture, here's the environment where this issue has been observed:

MCP Server: twenty.brainblendai.com/mcp – This is the specific server exhibiting the incorrect inputSchema format.
MCP Protocol Version Tested: 2024-11-05 and 2025-06-18 – The issue has been verified across multiple protocol versions, indicating a persistent problem.
Client: Claude Desktop (stdio transport via mcp-proxy) – This is the primary client where the impact has been observed, but as mentioned earlier, other clients may also be affected.

Understanding the environment helps to narrow down the scope of the issue and ensures that the fix is targeted correctly. By identifying the specific server and protocol versions, we can be confident that we're addressing the root cause of the problem.

Workaround

Necessity is the mother of invention, right? To keep things running smoothly while a proper fix is implemented, a clever workaround has been devised: a proxy server. This proxy server sits between the MCP server and Claude Desktop, and its job is to unwrap the jsonSchema key before passing the data on. Think of it as a translator, converting the server's dialect into a language that Claude Desktop understands.

This workaround is effective, but it's not a long-term solution. It adds complexity to the system and introduces an extra point of failure. Plus, it's essentially a band-aid on a bigger problem. We need to address the underlying issue in the MCP server itself to ensure a robust and sustainable solution.

While the proxy server buys us some time and keeps things running, it's crucial to remember that it's a temporary fix. The real goal is to eliminate the need for the proxy altogether by correcting the inputSchema format on the server side.

Fix Required

The solution here is straightforward, guys: remove the extra jsonSchema wrapper in the tools/list response. The inputSchema field should directly contain the JSON Schema object, without nesting it under a jsonSchema key. This aligns with the MCP specification and will ensure compatibility with clients like Claude Desktop.

This fix is crucial for a couple of reasons. First, it restores compatibility with Claude Desktop, allowing users to access the full range of tools provided by the MCP server. Second, it ensures adherence to the MCP specification, which promotes interoperability and reduces the risk of future compatibility issues. It's a win-win situation!

Implementing this fix will not only resolve the current problem but also prevent similar issues from arising in the future. By sticking to the established standards, we can create a more robust and reliable system for everyone.

It's worth noting that this issue seems to be affecting the BrainBlend AI hosted version at twenty.brainblendai.com. This means that users relying on this specific server are likely experiencing the problems described in this article. Awareness is the first step to solving any problem, so let's spread the word!

Furthermore, community implementations of the MCP server, such as mhenry3164/twenty-crm-mcp-server and OleApp-de/TwentyMCP, may or may not have this issue. It's always a good idea to double-check your own implementations to ensure they comply with the MCP specification. We're all in this together, and sharing knowledge helps everyone build better systems.

This issue is also related to Issue #12953, which discusses the creation of an official MCP server. A standardized and well-maintained server would go a long way in preventing these kinds of compatibility problems. It's something to keep in mind as we move forward and strive for a more seamless experience.

Finally, a big thank you to Twenty CRM for their awesome work! We appreciate the effort and dedication that goes into building these tools. By addressing this issue, we can make the system even better for everyone. Keep up the great work, guys!