Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Omit readOnly properties from OpenAPI tool input schemas (#5753)

Aarnav Noblecd8be219fbfe
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/schemas.py b/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
index 93c2e135b..3f9111306 100644
--- a/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
+++ b/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
@@ -786,11 +786,61 @@ def _combine_schemas_and_map_params(
result["$defs"] = schema_defs
if route.openapi_version and route.openapi_version.startswith("3"):
- result = convert_openapi_schema_to_json_schema(result, route.openapi_version)
+ result = _convert_input_schema(result, set(body_props), route.openapi_version)
return result, parameter_map
+def _convert_input_schema(
+ schema: dict[str, Any], body_property_names: set[str], openapi_version: str
+) -> dict[str, Any]:
+ """Convert a combined tool input schema to JSON Schema.
+
+ readOnly properties are removed: the server sets them, so a request does
+ not send them, and OpenAPI applies their ``required`` entries to responses
+ only. readOnly describes a property of an object, so at the top level only
+ the request body properties flattened into arguments (``body_property_names``)
+ can be removed. Parameters and a whole-body argument stay arguments even
+ when their own schema is marked readOnly; the objects inside them, and the
+ component schemas in ``$defs``, lose their readOnly properties.
+ """
+ properties = schema["properties"]
+ definitions = schema.get("$defs")
+
+ def convert(sub_schema: Any) -> Any:
+ return convert_openapi_schema_to_json_schema(
+ sub_schema, openapi_version, remove_read_only=True, definitions=definitions
+ )
+
+ body = convert(
+ {
+ "properties": {
+ k: v for k, v in properties.items() if k in body_property_names
+ },
+ "required": [n for n in schema["required"] if n in body_property_names],
+ }
+ )
+ converted = {
+ name: body["properties"][name]
+ if name in body_property_names
+ else convert(prop_schema)
+ for name, prop_schema in properties.items()
+ if name not in body_property_names or name in body["properties"]
+ }
+ result: dict[str, Any] = {
+ "type": "object",
+ "properties": converted,
+ "required": [
+ name
+ for name in schema["required"]
+ if name not in body_property_names or name in body.get("required", [])
+ ],
+ }
+ if definitions is not None:
+ result["$defs"] = {name: convert(d) for name, d in definitions.items()}
+ return result
+
+
def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
"""
Combines parameter and request body schemas into a single schema.
diff --git a/tests/server/providers/openapi/test_read_only_requests.py b/tests/server/providers/openapi/test_read_only_requests.py
new file mode 100644
index 000000000..4293d84b8
--- /dev/null
+++ b/tests/server/providers/openapi/test_read_only_requests.py
@@ -0,0 +1,197 @@
+"""readOnly properties are response-only, so tool input schemas omit them."""
+
+import json
+from typing import Any
+
+import httpx2
+import pytest
+
+from fastmcp import Client, FastMCP
+
+
+def pet_spec(openapi_version: str) -> dict[str, Any]:
+ pet_ref = {"$ref": "#/components/schemas/Pet"}
+ return {
+ "openapi": openapi_version,
+ "info": {"title": "Pets", "version": "1.0"},
+ "paths": {
+ "/owners/{owner_id}/pets": {
+ "post": {
+ "operationId": "create_pet",
+ "parameters": [
+ {
+ "name": "owner_id",
+ "in": "path",
+ "required": True,
+ "schema": {"$ref": "#/components/schemas/Id"},
+ }
+ ],
+ "requestBody": {
+ "required": True,
+ "content": {"application/json": {"schema": pet_ref}},
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "content": {"application/json": {"schema": pet_ref}},
+ }
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "Id": {"type": "integer", "readOnly": True},
+ "Pet": {
+ "type": "object",
+ "required": ["id", "name", "tag"],
+ "properties": {
+ "id": {"$ref": "#/components/schemas/Id"},
+ "name": {"type": "string", "readOnly": False},
+ "created_at": {"type": "string", "readOnly": True},
+ "tag": {"$ref": "#/components/schemas/Tag"},
+ },
+ },
+ "Tag": {
+ "type": "object",
+ "required": ["id", "label"],
+ "properties": {
+ "id": {"type": "integer", "readOnly": True},
+ "label": {"type": "string"},
+ },
+ },
+ }
+ },
+ }
+
+
[email protected]("openapi_version", ["3.0.3", "3.1.0"])
+async def test_input_schema_omits_read_only_properties(openapi_version: str):
+ server = FastMCP.from_openapi(
+ pet_spec(openapi_version), client=httpx2.AsyncClient(base_url="http://test")
+ )
+ async with Client(server) as client:
+ tool = (await client.list_tools())[0]
+
+ inputs = tool.input_schema
+ assert list(inputs["properties"]) == ["owner_id", "name", "tag"]
+ assert inputs["required"] == ["owner_id", "name", "tag"]
+ tag = inputs["properties"]["tag"]
+ assert list(tag["properties"]) == ["label"]
+ assert tag["required"] == ["label"]
+ assert "readOnly" not in json.dumps(inputs)
+
+ # Responses still carry readOnly properties.
+ output = tool.output_schema
+ assert output is not None
+ assert output["required"] == ["id", "name", "tag"]
+ assert "created_at" in output["properties"]
+ assert output["properties"]["tag"]["required"] == ["id", "label"]
+
+
+async def test_request_without_read_only_properties_is_sent():
+ requests: list[httpx2.Request] = []
+
+ def handler(request: httpx2.Request) -> httpx2.Response:
+ requests.append(request)
+ return httpx2.Response(
+ 201,
+ json={
+ "id": 3,
+ "name": "Rex",
+ "created_at": "2026-10-15",
+ "tag": {"id": 9, "label": "dog"},
+ },
+ )
+
+ api = httpx2.AsyncClient(
+ base_url="http://test", transport=httpx2.MockTransport(handler)
+ )
+ server = FastMCP.from_openapi(pet_spec("3.0.3"), client=api)
+ async with Client(server) as client:
+ result = await client.call_tool(
+ "create_pet", {"owner_id": 1, "name": "Rex", "tag": {"label": "dog"}}
+ )
+
+ assert requests[0].url.path == "/owners/1/pets"
+ assert json.loads(requests[0].content) == {"name": "Rex", "tag": {"label": "dog"}}
+ assert result.is_error is False
+ assert result.structured_content is not None
+ assert result.structured_content["id"] == 3
+
+
+async def test_whole_body_argument_omits_read_only_properties():
+ spec = pet_spec("3.1.0")
+ # A bulk create: an array body is passed as one argument.
+ spec["paths"]["/owners/{owner_id}/pets"]["post"]["requestBody"]["content"][
+ "application/json"
+ ]["schema"] = {"type": "array", "items": {"$ref": "#/components/schemas/Pet"}}
+ server = FastMCP.from_openapi(
+ spec, client=httpx2.AsyncClient(base_url="http://test")
+ )
+ async with Client(server) as client:
+ tool = (await client.list_tools())[0]
+
+ inputs = tool.input_schema
+ assert list(inputs["properties"]) == ["owner_id", "body"]
+ pet = inputs["properties"]["body"]["items"]
+ assert list(pet["properties"]) == ["name", "tag"]
+ assert pet["required"] == ["name", "tag"]
+ assert list(pet["properties"]["tag"]["properties"]) == ["label"]
+
+
+async def test_body_typed_by_read_only_component_stays_an_argument():
+ # readOnly applies to properties; a body that reuses a readOnly component
+ # as its root schema is still the request payload.
+ spec = pet_spec("3.0.3")
+ spec["paths"]["/owners/{owner_id}/pets"]["post"]["requestBody"]["content"][
+ "application/json"
+ ]["schema"] = {"$ref": "#/components/schemas/Id"}
+ server = FastMCP.from_openapi(
+ spec, client=httpx2.AsyncClient(base_url="http://test")
+ )
+ async with Client(server) as client:
+ tool = (await client.list_tools())[0]
+
+ inputs = tool.input_schema
+ assert list(inputs["properties"]) == ["owner_id", "body"]
+ assert inputs["properties"]["body"] == {"type": "integer"}
+ assert inputs["required"] == ["owner_id", "body"]
+
+
+async def test_object_parameter_omits_nested_read_only_properties():
+ spec = pet_spec("3.0.3")
+ filter_schema = {
+ "type": "object",
+ "required": ["id", "q"],
+ "properties": {
+ "id": {"type": "integer", "readOnly": True},
+ "q": {"type": "string"},
+ },
+ }
+ spec["components"]["schemas"]["Filter"] = filter_schema
+ # The same object inline and as a component $ref.
+ for name, schema in [
+ ("filter", filter_schema),
+ ("ref_filter", {"$ref": "#/components/schemas/Filter"}),
+ ]:
+ spec["paths"]["/owners/{owner_id}/pets"]["post"]["parameters"].append(
+ {
+ "name": name,
+ "in": "query",
+ "style": "deepObject",
+ "explode": True,
+ "schema": schema,
+ }
+ )
+ server = FastMCP.from_openapi(
+ spec, client=httpx2.AsyncClient(base_url="http://test")
+ )
+ async with Client(server) as client:
+ tool = (await client.list_tools())[0]
+
+ inputs = tool.input_schema
+ query_filter = inputs["properties"]["filter"]
+ assert list(query_filter["properties"]) == ["q"]
+ assert query_filter["required"] == ["q"]
+ assert inputs["properties"]["ref_filter"] == query_filter