{"record":{"id":"af8758dba13c55f6","repo":"zylon-ai/private-gpt","slug":"mcp-servers-are-not-supported-when-structured-outp","errorCode":null,"errorMessage":"MCP servers are not supported when structured output is enabled.","messagePattern":"MCP servers are not supported when structured output is enabled\\.","errorType":"validation","errorClass":"ValueError","httpStatus":422,"severity":"error","filePath":"private_gpt/server/chat/chat_models.py","lineNumber":366,"sourceCode":"                    if tool.context is None:\n                        tool.context = global_tool_context\n\n        has_structured_output = bool(self.output_config and self.output_config.format)\n        if self.response_format.type == ResponseFormatType.json_schema:\n            has_structured_output = True\n\n        # Check that we don't have tools when structured output is enabled\n        if has_structured_output:\n            if self.tools:\n                if self.response_format.type == ResponseFormatType.json_schema:\n                    raise ValueError(\n                        \"Tools are not supported when response_format is set to json_schema\"\n                    )\n                raise ValueError(\n                    \"Tools are not supported when structured output is enabled.\"\n                )\n            if self.mcp_servers:\n                raise ValueError(\n                    \"MCP servers are not supported when structured output is enabled.\"\n                )\n            if system.citations.enabled:\n                raise ValueError(\n                    \"Citations are not supported when structured output is enabled.\"\n                )\n\n        # Check unique tools\n        if self.tools:\n            tool_names = [tool.name for tool in self.tools]\n            if len(tool_names) != len(set(tool_names)):\n                raise ValueError(\n                    \"Duplicate tool names found in the tools list.\"\n                    f\" Provided tools: {self.tools}\"\n                    f\" Unique tool names: {set(tool_names)}\"\n                )\n\n        # Check tool use and result blocks","sourceCodeStart":348,"sourceCodeEnd":384,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/server/chat/chat_models.py#L348-L384","documentation":"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.","triggerScenarios":"Requesting json_schema response_format while mcp_servers=[...] lists connected MCP servers; a global MCP configuration applied to every request, including structured-output ones.","commonSituations":"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.","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."],"exampleFix":"# before\nbody = {\"messages\": m, \"mcp_servers\": [\"fs\"], \"response_format\": {\"type\": \"json_schema\"}}\n\n# after\nbody = {\"messages\": m, \"response_format\": {\"type\": \"json_schema\"}}","handlingStrategy":"validation","validationCode":"if structured_output_enabled(body):\n    body.pop('mcp_servers', None)","typeGuard":"def mcp_compatible_with_structured(body: dict) -> bool:\n    structured = bool((body.get('output_config') or {}).get('format')) or \\\n        body.get('response_format', {}).get('type') == 'json_schema'\n    return not (structured and body.get('mcp_servers'))","tryCatchPattern":"except ValidationError as e:\n    if 'MCP servers' in str(e):\n        body.pop('mcp_servers', None); retry()\n    else:\n        raise","preventionTips":["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"],"tags":["validation","mcp","structured-output","tools"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}