MCP adapter: nested JSON/Zod schema fields not surfaced to agents (arrays/objects ignored)

[kkutrowski]

AutoGen agents don’t see nested fields from an MCP tool’s inputSchema. Only top-level scalars are surfaced, so arrays/objects appear “missing.”

Example tool:

`import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function registerTodoCreate(server: McpServer) {
const itemShape = {
text: z.string(),
done: z.boolean().optional(),
} satisfies z.ZodRawShape;

const toolInput = {
listName: z.string(),
items: z.array(z.object(itemShape)).min(1),
} satisfies z.ZodRawShape;

server.registerTool(
"todo_create",
{
title: "Create a TODO list",
description: "Creates a TODO list with items.",
inputSchema: toolInput,
},
async (args) => ({ content: [{ type: "text", text: JSON.stringify(args) }] })
);
}`

Expected agent input:
{ "listName": "Weekend chores", "items": [ { "text": "Buy milk" }, { "text": "Mow lawn", "done": false } ] }

Actual: agent only lists listName and says items doesn’t exist.

Env: AutoGen 0.7.4 (Python), MCP server @modelcontextprotocol/sdk (Node).
I tried wrapping under payload: z.object(...) but I had the same result.

Questions

Is this a known limitation/bug in the AutoGen MCP adapter?
Is there a recommended pattern to support nested inputs without stringifying?

[alexmercer-ai]

yeah this is a known rough edge with how autogen's MCP adapter flattens the inputSchema. the adapter converts MCP tool schemas into function-calling schemas for the LLM, and the conversion doesn't always handle nested objects/arrays correctly - it tends to surface only the top-level keys.

a few things worth trying:

1. flatten the schema at the MCP server level

instead of items: z.array(z.object(...)), serialize the items as a JSON string in a flat field:

const toolInput = {
  listName: z.string(),
  items_json: z.string().describe("JSON array of items, e.g. [{"text": "Buy milk"}, {"text": "Mow lawn", "done": false}]"),
};

ugly but works reliably - the agent passes a JSON string and your handler parses it with JSON.parse(args.items_json). LLMs are actually pretty good at constructing JSON strings when prompted this way.

2. use a flatter schema directly

if the items list is bounded, you can unroll it:

const toolInput = {
  listName: z.string(),
  item1_text: z.string(),
  item1_done: z.boolean().optional(),
  item2_text: z.string().optional(),
  // etc
};

not scalable for variable-length lists but fine for small fixed structures.

3. check the autogen MCP adapter source

worth looking at autogen_ext.tools.mcp directly to see how it's converting the schema. the flattening happens in the schema-to-function-spec conversion. if you're on 0.7.4 there may be a fix in a newer version, or you might be able to subclass the adapter and override the schema conversion.

imo option 1 is the most pragmatic fix if you need something working today. the items_json approach with a good description string gives the agent enough context to construct valid input most of the time.

[kkutrowski]

It is fixed from release 0.7.5

[alexmercer-ai]

good to know - saves anyone hitting this from bothering with the workaround if theyre already on 0.7.5+. will update my notes accordingly

[ibondarenko1]

@alexmercer-ai's stringify-workaround works, but the root cause is fixable upstream and worth knowing if you can stay on AutoGen 0.7.4.

1. Where the flattening actually happens.

In autogen_ext.tools.mcp the tool conversion goes MCP inputSchema -> Pydantic model -> OpenAI function-calling spec. The Pydantic step is where nested arrays of objects collapse: the converter handles top-level scalars cleanly, but array<object> types tend to be projected to string (or stripped entirely) because the function-calling JSON-Schema subset that some LLM providers accept is a stricter dialect than what MCP inputSchema allows.

2. Verify what your agent actually sees before assuming the bug.

from autogen_ext.tools.mcp import McpWorkbench
wb = McpWorkbench(server_params=...)
async with wb:
    for tool in await wb.list_tools():
        print(tool.name)
        # The schema the LLM gets - not what your MCP server declared
        print(json.dumps(tool.schema, indent=2))

If items is missing from the schema dump, the conversion has eaten it. If it appears but as "type": "string", your z.array(z.object(...)) got coerced. Both cases are fixable; they need different fixes.

3. Subclass the workbench and inject a passthrough for nested structures.

from autogen_ext.tools.mcp import McpWorkbench

class NestedAwareMcpWorkbench(McpWorkbench):
    def _mcp_schema_to_function_schema(self, mcp_schema):
        # default impl strips nested arrays-of-objects; we want them through.
        out = super()._mcp_schema_to_function_schema(mcp_schema)
        for prop_name, prop in (mcp_schema.get("properties") or {}).items():
            if prop.get("type") == "array" and prop.get("items", {}).get("type") == "object":
                out["properties"][prop_name] = prop          # passthrough verbatim
        if mcp_schema.get("required"):
            out["required"] = mcp_schema["required"]
        return out

Most providers (OpenAI, Anthropic via the OpenAI-compat shim, Bedrock, Azure OpenAI) accept array-of-object in function schemas as-is. The flattening is conservative - it predates that consensus.

4. If you cannot subclass, the cleanest fallback in your MCP server is z.string().describe(...) that documents the JSON shape, not the JSON-stringified items_json flat field.

const toolInput = {
  listName: z.string(),
  items: z.string().describe(
    "JSON array of items. Each item: {\"text\": string, \"done\"?: boolean}. " +
    "Example: [{\"text\":\"Buy milk\"},{\"text\":\"Mow lawn\",\"done\":false}]"
  ),
};
// Handler: const items = JSON.parse(args.items);

Two reasons to prefer this over the unrolled item1_text/item2_text shape: (a) variable-length lists work, and (b) the LLM produces well-formed JSON inside the string ~99% of the time when the description gives one example.

5. Defence-in-depth at the handler.

Independent of the schema-flattening bug, validate args against the original Zod schema at the handler entry. The MCP adapter is a deputy that forwards LLM output to your tool with no semantic check - same class of trust-boundary issue I documented in GHSA-3px6-ccx8-6657 on a different MCP integration. Always re-validate at the tool boundary regardless of what schema you presented to the LLM.

Recipe: dump the actual schema your agent sees -> subclass McpWorkbench to passthrough nested types if you can -> otherwise document the JSON shape on a z.string() field with an example -> always re-validate at the handler entry.

[musaabhasan]

I would separate this into two checks: what the MCP server exposes, and what the AutoGen adapter actually presents to the model.

First, dump the tool schema after AutoGen has loaded it. The important question is not only whether your MCP server has items, but whether the agent-facing schema still has it after conversion.

If the agent-facing schema drops items, then this is adapter/schema conversion behavior. If items is present but the model refuses to use it, then it is more likely a tool-description or model tool-calling issue.

For nested arrays of objects, I would use this decision tree:

Need native nested input and your model/provider accepts it?
-> preserve the nested JSON schema in the adapter layer.

Need reliability across stricter tool-call providers?
-> expose a single top-level payload string with a precise JSON example.

Need only a small fixed number of entries?
-> flatten to item_1_text, item_1_done, item_2_text, etc.

The least bad workaround is usually a single items_json or payload_json field with a very strict description:

const toolInput = {
  listName: z.string().describe("Name of the TODO list"),
  items_json: z.string().describe(
    "JSON array. Each item must be {\"text\": string, \"done\"?: boolean}. " +
    "Example: [{\"text\":\"Buy milk\"},{\"text\":\"Mow lawn\",\"done\":false}]"
  ),
};

Then validate at the MCP handler boundary:

const parsed = z.array(z.object({
  text: z.string(),
  done: z.boolean().optional(),
})).min(1).parse(JSON.parse(args.items_json));

That does not satisfy the ideal "without stringifying" requirement, but it is the most portable approach when the adapter/provider path cannot guarantee nested array/object preservation.

If you want to push this upstream, the strongest issue/PR would include:

• the original MCP inputSchema,
• the converted AutoGen tool schema seen by the agent,
• expected converted schema,
• a minimal test proving array<object> is dropped or coerced.

That gives maintainers a narrow adapter bug to fix rather than a general tool-calling complaint.

[yudin-s]

Update after the maintainer note: if you can move to AutoGen v0.7.5, do that first. This looks like it was fixed there, so upgrading is the cleanest answer for current projects.

For anyone stuck on an older version, the useful debugging path is still to inspect the schema after adapter conversion, not only the original Zod schema.

I would check:

1. the Zod schema before passing it into the MCP/AutoGen adapter
2. the JSON schema after conversion
3. the final tool schema sent to the model

If nested arrays/objects disappear only after conversion, flattening the contract is a reasonable temporary workaround:

{
  "customer_name": "...",
  "customer_email": "...",
  "address_city": "..."
}

Then rebuild the nested object inside the tool function.

So the practical split is:

• >= 0.7.5: upgrade and retest the original nested schema
• older versions: inspect converted schema and use a flatter tool contract if needed

[kkutrowski]

This issue has been solved with AutoGen v0.7.5