MCP middleware swallows tool errors — outputSchema validation hides real error messages

[mrjasonroy]

Problem

When a tool throws an exception, the middleware in databricks-mcp-server/databricks_mcp_server/middleware.py catches it and returns a ToolResult without structured_content. Because the tool has an outputSchema (auto-generated by FastMCP from return type annotations), the MCP SDK validation rejects the response with:

Output validation error: outputSchema defined but no structured output returned

This replaces the actual error message with a generic validation error, making debugging impossible. The user never sees the real exception.

Example

# execute_sql with a SQL syntax the Databricks API doesn't support
SELECT name FROM (LIST 's3://bucket/prefix/') WHERE name LIKE '%2026%'

Instead of seeing the actual SQL error, we get:

Output validation error: outputSchema defined but no structured output returned

Root Cause

PR #411 (beb7be5) attempted to fix this but hit a circular problem:

1. Adding structured_content to error responses → MCP SDK validates the error dict against the tool's outputSchema → fails because error shape doesn't match return type
2. Omitting structured_content from error responses → MCP SDK rejects because outputSchema exists but no structured output → generic error shown

The current code (v0.1.9) takes approach #2, which avoids crashes but swallows the real error.

Suggested Fix

Option A: Remove outputSchema from tool definitions entirely (tools can still return structured data without declaring a schema).

Option B: Define an error-aware outputSchema that accepts either the success type OR an error envelope via anyOf/oneOf.

Option C: Use isError=True on the ToolResult to signal the MCP SDK to skip outputSchema validation for error responses (if supported).

Impact

This affects every tool in the MCP server that has a return type annotation. Any exception is silently swallowed and replaced with the generic validation error. We've been debugging SQL queries, S3 operations, and job runs with zero visibility into actual failures.

Environment

• ai-dev-kit: v0.1.9
• fastmcp: 3.1.1 (also tested 3.2.3)
• mcp: 1.26.0 (also tested 1.27.0)
• Python: 3.11.14
• Claude Code (CLI)

[mrjasonroy]

To clarify severity — this isn't just exotic SQL syntax. Simple query errors are swallowed too:

-- Typo in column name
SELECT nonexistent_column FROM gold.gs_entities.users LIMIT 1

Instead of Column 'nonexistent_column' not found, we get:

Output validation error: outputSchema defined but no structured output returned

Same for wrong table names, syntax errors, permission issues — any SQL error at all. The middleware catches the exception, drops the message, and returns the generic validation error. This makes the execute_sql tool nearly unusable for iterative query development since you can't see what went wrong.

[mrjasonroy]

Fix Found

The fix is simple: remove the except Exception and except TimeoutError handlers from the middleware and let exceptions propagate to FastMCP.

FastMCP already handles this correctly:

1. FastMCP.call_tool() catches all exceptions at line 93
2. Wraps them as ToolError(f"Error calling tool {name!r}: {e}")
3. MCP SDK converts ToolError → CallToolResult(isError=True)
4. isError=True tells the SDK to skip outputSchema validation
5. The real error message reaches the agent
6. The MCP server stays up

The middleware was intercepting exceptions before FastMCP could handle them, converting them to normal (non-error) ToolResult responses. Since these didn't have structured_content but the tool had an outputSchema, the SDK rejected them with the generic validation error — hiding the real message.

Minimal fix (middleware.py)

async def on_call_tool(self, context, call_next):
    try:
        result = await call_next(context)
        # ... structured_content fixup for successful responses ...
        return result
    except anyio.get_cancelled_exc_class():
        raise  # Let MCP SDK handle cancellation
    # All other exceptions propagate to FastMCP -> ToolError -> isError=True

The timeout handler can also be removed — FastMCP already handles httpx.TimeoutException with a user-friendly message (line 102-105 of FastMCP.call_tool()).

Verified

Tested with the fix: SQL errors like UNRESOLVED_COLUMN.WITH_SUGGESTION now show the real error message with column suggestions instead of the generic outputSchema validation error.