zylon-ai/private-gpt · error · ValueError

MCP servers are not supported when structured output is…

Error message

MCP servers are not supported when structured output is enabled.

What it means

Third branch of the structured-output guard in ChatBody: MCP servers (external tool providers) are attached to the request while structured output (output_config.format or json_schema response_format) is enabled. Since MCP servers implicitly contribute tools, they are incompatible with schema-constrained responses and the validator rejects the combination.

Solutions

Omit mcp_servers in structured-output requests (build the body per mode).
Scope MCP server configuration to specific routes/features instead of global defaults.
If MCP tools are essential, drop the structured-output format for that call and parse the response manually.

Example fix

# before
body = {"messages": m, "mcp_servers": ["fs"], "response_format": {"type": "json_schema"}}

# after
body = {"messages": m, "response_format": {"type": "json_schema"}}

Defensive patterns

Strategy: validation

Validate before calling

if structured_output_enabled(body):
    body.pop('mcp_servers', None)

Type guard

def mcp_compatible_with_structured(body: dict) -> bool:
    structured = bool((body.get('output_config') or {}).get('format')) or \
        body.get('response_format', {}).get('type') == 'json_schema'
    return not (structured and body.get('mcp_servers'))

Try / catch

except ValidationError as e:
    if 'MCP servers' in str(e):
        body.pop('mcp_servers', None); retry()
    else:
        raise

Prevention

Scope MCP server config per route, not deployment-wide
Add a config lint that flags mcp_servers + structured output combos
Document the incompatibility in your API client wrappers

When it happens

Trigger: Requesting json_schema response_format while mcp_servers=[...] lists connected MCP servers; a global MCP configuration applied to every request, including structured-output ones.

Common situations: App-level MCP integration turned on by default while adding a new structured-output endpoint; config files where mcp_servers is set globally rather than per-route.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/af8758dba13c55f6. Report an issue: GitHub.

Appendix: source

Thrown at private_gpt/server/chat/chat_models.py:366

                    if tool.context is None:
                        tool.context = global_tool_context

        has_structured_output = bool(self.output_config and self.output_config.format)
        if self.response_format.type == ResponseFormatType.json_schema:
            has_structured_output = True

        # Check that we don't have tools when structured output is enabled
        if has_structured_output:
            if self.tools:
                if self.response_format.type == ResponseFormatType.json_schema:
                    raise ValueError(
                        "Tools are not supported when response_format is set to json_schema"
                    )
                raise ValueError(
                    "Tools are not supported when structured output is enabled."
                )
            if self.mcp_servers:
                raise ValueError(
                    "MCP servers are not supported when structured output is enabled."
                )
            if system.citations.enabled:
                raise ValueError(
                    "Citations are not supported when structured output is enabled."
                )

        # Check unique tools
        if self.tools:
            tool_names = [tool.name for tool in self.tools]
            if len(tool_names) != len(set(tool_names)):
                raise ValueError(
                    "Duplicate tool names found in the tools list."
                    f" Provided tools: {self.tools}"
                    f" Unique tool names: {set(tool_names)}"
                )

        # Check tool use and result blocks

View on GitHub (pinned to 4a030776a3)