|
| 1 | +# ChatGPT + FastMCP 3.0 Compatibility Guide |
| 2 | + |
| 3 | +This document describes the compatibility issues between ChatGPT's MCP integration and FastMCP 3.0 servers, along with the solutions implemented in this project. |
| 4 | + |
| 5 | +## Background |
| 6 | + |
| 7 | +ChatGPT adopted MCP in March 2025. However, ChatGPT uses "strict mode" for function calling, which has stricter JSON Schema requirements than the base MCP specification. |
| 8 | + |
| 9 | +## Issue 1: Missing `additionalProperties: false` |
| 10 | + |
| 11 | +**GitHub Issues:** |
| 12 | +- [github-mcp-server #376](https://github.com/github/github-mcp-server/issues/376) |
| 13 | +- [FastMCP #855](https://github.com/jlowin/fastmcp/issues/855) |
| 14 | + |
| 15 | +**Problem:** ChatGPT strict mode requires `additionalProperties: false` on every object in the schema. Standard MCP schemas (and Pydantic-generated schemas) don't include this. |
| 16 | + |
| 17 | +**Error:** |
| 18 | +``` |
| 19 | +Invalid schema for function 'add_issue_comment': In context=(), 'additionalProperties' is required to be supplied and to be false. |
| 20 | +``` |
| 21 | + |
| 22 | +**Solution:** Recursively add `additionalProperties: false` to all object schemas. |
| 23 | + |
| 24 | +```python |
| 25 | +def _add_additional_properties_false(schema: dict) -> dict: |
| 26 | + """Recursively add additionalProperties: false to all objects.""" |
| 27 | + if not isinstance(schema, dict): |
| 28 | + return schema |
| 29 | + |
| 30 | + result = dict(schema) |
| 31 | + |
| 32 | + # If this is an object with properties, add additionalProperties: false |
| 33 | + if result.get("type") == "object" or "properties" in result: |
| 34 | + if "additionalProperties" not in result: |
| 35 | + result["additionalProperties"] = False |
| 36 | + |
| 37 | + # Recurse into properties |
| 38 | + if "properties" in result: |
| 39 | + result["properties"] = { |
| 40 | + k: _add_additional_properties_false(v) |
| 41 | + for k, v in result["properties"].items() |
| 42 | + } |
| 43 | + |
| 44 | + # Recurse into items (for arrays) |
| 45 | + if "items" in result and isinstance(result["items"], dict): |
| 46 | + result["items"] = _add_additional_properties_false(result["items"]) |
| 47 | + |
| 48 | + return result |
| 49 | +``` |
| 50 | + |
| 51 | +## Issue 2: Optional Fields Must Be in `required` Array |
| 52 | + |
| 53 | +**Problem:** ChatGPT strict mode requires ALL properties to be listed in the `required` array. Optional fields should use type arrays like `["string", "null"]` instead of being omitted from `required`. |
| 54 | + |
| 55 | +**ChatGPT Documentation:** |
| 56 | +> "If you turn on `strict: true` in the function calling schema, then you have to list all of your fields under `required`." |
| 57 | +
|
| 58 | +**Before (Standard JSON Schema):** |
| 59 | +```json |
| 60 | +{ |
| 61 | + "type": "object", |
| 62 | + "properties": { |
| 63 | + "title": {"type": "string"}, |
| 64 | + "notes": {"type": "string"} |
| 65 | + }, |
| 66 | + "required": ["title"] |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +**After (ChatGPT Strict Mode):** |
| 71 | +```json |
| 72 | +{ |
| 73 | + "type": "object", |
| 74 | + "properties": { |
| 75 | + "title": {"type": "string"}, |
| 76 | + "notes": {"type": ["string", "null"]} |
| 77 | + }, |
| 78 | + "required": ["title", "notes"], |
| 79 | + "additionalProperties": false |
| 80 | +} |
| 81 | +``` |
| 82 | + |
| 83 | +**Solution:** Add all properties to `required` and use type arrays for optional fields. |
| 84 | + |
| 85 | +```python |
| 86 | +def _make_all_fields_required(schema: dict) -> dict: |
| 87 | + """Add all properties to required array, using type arrays for optional fields.""" |
| 88 | + if not isinstance(schema, dict): |
| 89 | + return schema |
| 90 | + |
| 91 | + result = dict(schema) |
| 92 | + |
| 93 | + if "properties" in result: |
| 94 | + all_props = list(result["properties"].keys()) |
| 95 | + current_required = set(result.get("required", [])) |
| 96 | + |
| 97 | + # For fields not currently required, make them nullable |
| 98 | + new_properties = {} |
| 99 | + for prop_name, prop_schema in result["properties"].items(): |
| 100 | + prop_schema = _make_all_fields_required(prop_schema) # Recurse first |
| 101 | + |
| 102 | + if prop_name not in current_required: |
| 103 | + # Add null to type for optional fields |
| 104 | + prop_schema = dict(prop_schema) |
| 105 | + if "type" in prop_schema: |
| 106 | + current_type = prop_schema["type"] |
| 107 | + if isinstance(current_type, str) and current_type != "null": |
| 108 | + prop_schema["type"] = [current_type, "null"] |
| 109 | + elif isinstance(current_type, list) and "null" not in current_type: |
| 110 | + prop_schema["type"] = current_type + ["null"] |
| 111 | + |
| 112 | + new_properties[prop_name] = prop_schema |
| 113 | + |
| 114 | + result["properties"] = new_properties |
| 115 | + result["required"] = all_props |
| 116 | + |
| 117 | + # Recurse into items |
| 118 | + if "items" in result and isinstance(result["items"], dict): |
| 119 | + result["items"] = _make_all_fields_required(result["items"]) |
| 120 | + |
| 121 | + return result |
| 122 | +``` |
| 123 | + |
| 124 | +## Issue 3: `anyOf` Not Supported |
| 125 | + |
| 126 | +**Problem:** ChatGPT strict mode doesn't support `anyOf`, `oneOf`, or `allOf` constructs. Pydantic generates `anyOf` for `Optional[T]` types. |
| 127 | + |
| 128 | +**Error:** |
| 129 | +``` |
| 130 | +Invalid schema: anyOf is not supported in strict mode |
| 131 | +``` |
| 132 | + |
| 133 | +**Solution:** Flatten `anyOf` constructs to JSON Schema type arrays. This is the same solution we use for n8n compatibility - see `docs/n8n-fastmcp-compatibility.md`. |
| 134 | + |
| 135 | +## Complete Transformation Pipeline |
| 136 | + |
| 137 | +We apply all transformations to all requests (ChatGPT requirements are a superset of n8n): |
| 138 | + |
| 139 | +```python |
| 140 | +def _transform_schema_for_clients(schema: dict) -> dict: |
| 141 | + """Apply all client compatibility transformations.""" |
| 142 | + # Step 1: Flatten anyOf (needed for both n8n and ChatGPT) |
| 143 | + schema = _flatten_anyof_for_n8n(schema) |
| 144 | + |
| 145 | + # Step 2: Add additionalProperties: false (ChatGPT) |
| 146 | + schema = _add_additional_properties_false(schema) |
| 147 | + |
| 148 | + # Step 3: Make all fields required (ChatGPT) |
| 149 | + schema = _make_all_fields_required(schema) |
| 150 | + |
| 151 | + return schema |
| 152 | +``` |
| 153 | + |
| 154 | +## Why This Works for Both n8n and ChatGPT |
| 155 | + |
| 156 | +| Transformation | n8n needs? | ChatGPT needs? | Breaks either? | |
| 157 | +|----------------|------------|----------------|----------------| |
| 158 | +| Flatten `anyOf` | Yes | Yes | No | |
| 159 | +| `additionalProperties: false` | No | Yes | No (n8n ignores) | |
| 160 | +| All fields in `required` | No | Yes | No (n8n ignores) | |
| 161 | +| Strip extra params | Yes | No | No (ChatGPT doesn't send them) | |
| 162 | + |
| 163 | +## Testing ChatGPT Compatibility |
| 164 | + |
| 165 | +1. **Enable debug logging:** |
| 166 | + ```bash |
| 167 | + export THINGS_MCP_DEBUG_SCHEMA=1 |
| 168 | + ``` |
| 169 | + |
| 170 | +2. **Use ngrok for HTTPS** (ChatGPT requires HTTPS): |
| 171 | + ```bash |
| 172 | + ngrok http 127.0.0.1:8009 |
| 173 | + ``` |
| 174 | + |
| 175 | +3. **Connect ChatGPT to the ngrok HTTPS URL** |
| 176 | + |
| 177 | +4. **Verify tools are listed and callable** |
| 178 | + |
| 179 | +## Recommendations for FastMCP Team |
| 180 | + |
| 181 | +### 1. Built-in Schema Transformations |
| 182 | + |
| 183 | +Consider adding built-in schema transformation for common clients: |
| 184 | + |
| 185 | +```python |
| 186 | +server = FastMCP( |
| 187 | + "MyServer", |
| 188 | + schema_compat="strict" # Applies ChatGPT-compatible transformations |
| 189 | +) |
| 190 | +``` |
| 191 | + |
| 192 | +### 2. Pydantic Model Configuration |
| 193 | + |
| 194 | +Consider Pydantic configuration that generates strict-mode-compatible schemas: |
| 195 | + |
| 196 | +```python |
| 197 | +class ToolInput(BaseModel): |
| 198 | + model_config = ConfigDict( |
| 199 | + json_schema_extra={"additionalProperties": False} |
| 200 | + ) |
| 201 | +``` |
| 202 | + |
| 203 | +### 3. Documentation |
| 204 | + |
| 205 | +Document the differences between MCP spec schemas and what various clients actually require. |
| 206 | + |
| 207 | +## References |
| 208 | + |
| 209 | +- [FastMCP Issue #855 - OpenAI Responses API](https://github.com/jlowin/fastmcp/issues/855) |
| 210 | +- [github-mcp-server Issue #376 - additionalProperties](https://github.com/github/github-mcp-server/issues/376) |
| 211 | +- [OpenAI Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) |
| 212 | +- [OpenAI Community: Schema additionalProperties](https://community.openai.com/t/schema-additionalproperties-must-be-false-when-strict-is-true/929996) |
| 213 | + |
| 214 | +## See Also |
| 215 | + |
| 216 | +- `docs/n8n-fastmcp-compatibility.md` - n8n-specific compatibility (anyOf flattening, parameter stripping) |
0 commit comments