MCPToolResultContentTypeError
mcp.exceptions.MCPToolResultContentTypeError
Stack trace
mcp.exceptions.MCPToolResultContentTypeError: Expected content type 'application/json' but received 'text/plain'.
File "app.py", line 42, in run_tool
result = tool.execute()
File "mcp/tools.py", line 88, in execute
raise MCPToolResultContentTypeError(f"Expected content type '{expected}' but received '{actual}'") Why it happens
MCP tools expect results in a specific content type, typically 'application/json'. If the tool returns a different content type like 'text/plain' or 'text/html', the MCP framework cannot parse the result correctly and raises this error. This often happens when the tool's output format or headers are misconfigured or when the tool encounters an internal error and returns an error page instead of the expected JSON.
Detection
Monitor tool execution responses and assert the content type matches the expected MIME type before parsing. Log the raw response headers and body when a mismatch occurs to catch this error early.
Causes & fixes
The MCP tool returned plain text or HTML instead of JSON due to an internal error or misconfiguration.
Ensure the tool's output is correctly formatted as JSON and that the Content-Type header is set to 'application/json'. Fix any internal errors causing fallback to HTML or plain text.
The MCP tool's HTTP response headers do not specify the correct Content-Type, causing the MCP framework to misinterpret the result.
Configure the tool or server to send the correct Content-Type header explicitly, matching the expected format.
The MCP tool was invoked with incorrect parameters causing it to return an error message or help text in plain text format.
Validate and correct the parameters passed to the tool to ensure it returns the expected JSON result.
Code: broken vs fixed
from mcp import MCPTool
tool = MCPTool(name="example_tool")
result = tool.execute() # Raises MCPToolResultContentTypeError due to wrong content type
print(result)import os
from mcp import MCPTool
os.environ["MCP_API_KEY"] = os.environ.get("MCP_API_KEY", "") # Use environment variable for auth
tool = MCPTool(name="example_tool")
# Ensure tool is configured to return JSON with correct headers
result = tool.execute()
print(result) # Works without content type errorWorkaround
Catch MCPToolResultContentTypeError and attempt to parse the raw response body manually or log it for debugging, then retry the tool execution after fixing the input or environment.
Prevention
Use strict content type validation and schema enforcement at the MCP tool interface level, and implement automated tests to verify tool outputs conform to expected content types before deployment.