[BUG] Claude Code MCP Protocol Violation: Incorrect Resource Content Validation

[keithrbennett]

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude Code MCP Protocol Violation: Incorrect Resource Content Validation

Summary

Claude Code's MCP client implementation contains a critical bug that incorrectly validates resource content in tool responses, making it incompatible with MCP servers that follow the official Model Context Protocol specification. The client rejects valid TextResourceContents objects that contain a text field, instead requiring a uri field that is not mandated by the MCP specification.

Bug Details

Product: Claude Code (claude.ai/code) Component: MCP (Model Context Protocol) client implementation Impact: High - Breaks compatibility with spec-compliant MCP servers Severity: Critical - Core MCP functionality non-functional

Expected Behavior (Per MCP Specification)

According to the official MCP specification at https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-06-18/schema.ts, TextResourceContents objects are defined as:

export interface TextResourceContents extends ResourceContents {
  text: string;
}

This allows MCP tool responses to return resource content with a text field containing the actual content, which is the correct format for text-based resources.

Actual Behavior (Claude Code Bug)

Claude Code's MCP client implementation incorrectly rejects valid TextResourceContents objects and instead requires:

1. A uri field (which is not required by the MCP spec for text resources)
2. Rejection of the text field (which is the primary field for TextResourceContents)

Error Output

When calling MCP tools through Claude Code, the following Zod validation error occurs:

{
  "code": "invalid_union",
  "unionErrors": [
    {
      "issues": [
        {
          "received": "resource",
          "code": "invalid_literal",
          "expected": "text",
          "path": ["content", 0, "type"],
          "message": "Invalid literal value, expected \"text\""
        },
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "undefined",
          "path": ["content", 0, "text"],
          "message": "Required"
        }
      ]
    },
    {
      "issues": [
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "undefined",
          "path": ["content", 0, "resource", "uri"],
          "message": "Required"
        }
      ]
    }
  ]
}

Example of Spec-Compliant Response (Rejected by Claude Code)

{
  "content": [
    {
      "type": "resource",
      "resource": {
        "mimeType": "application/json",
        "text": "{\"file\": \"example.rb\", \"coverage\": 85.5}",
        "name": "coverage_data.json"
      }
    }
  ]
}

Example of What Claude Code Incorrectly Expects

Claude Code appears to expect one of these formats:

{
  "content": [
    {
      "type": "resource_link",
      "name": "coverage_data.json",
      "uri": "file://some_uri"
    }
  ]
}

or

{
  "content": [
    {
      "type": "resource",
      "resource": {
        "uri": "file://some_uri",
        "blob": "base64_encoded_data"
      }
    }
  ]
}

Root Cause Analysis

Claude Code's MCP client implementation appears to be using an incorrect Zod schema that:

1. Mandates uri fields for all resource types
2. Rejects the text field that is central to TextResourceContents
3. Does not properly implement the union type for TextResourceContents | BlobResourceContents

Impact

This bug prevents Claude Code from working with any MCP server that returns text-based resource content following the official specification, including:

• Coverage analysis tools (like simplecov-mcp)
• Configuration management tools
• Code analysis tools
• Documentation servers
• Any tool that returns structured data as text resources

Fix Required

Claude Code's MCP client validation logic needs to be updated to properly support the official MCP specification, specifically:

1. Accept TextResourceContents objects with text fields
2. Remove the incorrect requirement for uri fields on text resources
3. Implement proper union type validation for TextResourceContents | BlobResourceContents

References

• Official MCP Specification: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-06-18/schema.ts
• MCP Documentation: https://modelcontextprotocol.io/specification/2025-06-18
• Example Affected MCP Server: https://github.com/keithrbennett/simplecov-mcp (Ruby gem implementing MCP for SimpleCov coverage analysis)

Test Case

To verify the fix, Claude Code should successfully process this valid MCP tool response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "resource",
        "resource": {
          "mimeType": "application/json",
          "text": "{\"summary\": {\"covered\": 31, \"total\": 53, \"pct\": 58.49}}",
          "name": "coverage_summary.json"
        }
      }
    ],
    "isError": false
  }
}

This response format is 100% compliant with the MCP specification but currently fails validation in Claude Code.

What Should Happen?

Claude Code should accept and process the JSON as produced by the MCP server (in my case, the simplecov-mcp server).

Error Messages/Logs

## Error Output

When calling MCP tools through Claude Code, the following Zod validation error occurs:


{
  "code": "invalid_union",
  "unionErrors": [
    {
      "issues": [
        {
          "received": "resource",
          "code": "invalid_literal",
          "expected": "text",
          "path": ["content", 0, "type"],
          "message": "Invalid literal value, expected \"text\""
        },
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "undefined",
          "path": ["content", 0, "text"],
          "message": "Required"
        }
      ]
    },
    {
      "issues": [
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "undefined",
          "path": ["content", 0, "resource", "uri"],
          "message": "Required"
        }
      ]
    }
  ]
}

Steps to Reproduce

Reproduction Steps

1. Set up an MCP server that returns TextResourceContents following the official specification
2. Configure Claude Code to connect to this MCP server
3. Call any MCP tool that returns resource content with type: "resource" and resource.text
4. Observe validation error from Claude Code

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

1.0.126

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Other

Additional Information

No response

[mintmcqueen]

+1

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[keithrbennett]

Sorry, my software no longer uses that protocol so I am unable to test it.