zylon-ai/private-gpt · error · ValueError

MCP servers are not supported when structured output is enab

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.

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)

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.