typescript

Don't put a union at the top of an MCP tool schema

I was building an MCP server with Mastra and Zod, exposing tools to Claude Code. Out of nowhere, Claude Code started telling me the MCP server was not authorized and showed zero tools — even ones that worked fine a minute ago.

The culprit: I had added one new tool whose outputSchema was a z.discriminatedUnion(...) at the root. One bad tool took down discovery for the whole server.

MCP transports tool schemas as JSON Schema. Clients (including Claude Code) validate that every tool's input and output schema has type: "object" at the root. A union serializes as { anyOf: [...] } with no root object type, fails that check, and the client rejects the entire tools/list response. The misleading part is the error: Claude Code surfaces it as a generic auth failure, not a schema problem.

Wrap the union in an outer z.object({ ... }). You keep the discriminated union semantics — only the root shape changes from a union to an object with one field that contains the union.

If an MCP server suddenly shows no tools or an auth error after you added or edited one tool, suspect the schema before suspecting auth. Check every new tool's inputSchema and outputSchema — if either starts with a union, wrap it.

import { z } from "zod"
import { createTool } from "@mastra/core"

// Reusable union — fine on its own
const resultUnion = z.discriminatedUnion("type", [
  z.object({ type: z.literal("ok"), pageId: z.string() }),
  z.object({ type: z.literal("error"), message: z.string() }),
])

// BAD — top-level union breaks MCP tool discovery.
// Claude Code reports "not authorized" and hides ALL tools on the server.
const brokenTool = createTool({
  id: "do-thing",
  description: "Does a thing",
  inputSchema: z.object({ pageId: z.string() }),
  outputSchema: resultUnion, // <-- root is { anyOf: [...] }, no type:"object"
  execute: async () => ({ type: "ok" as const, pageId: "x" }),
})

// GOOD — wrap the union in an outer z.object.
// Discriminator semantics are preserved; the root is now a proper object.
const workingTool = createTool({
  id: "do-thing",
  description: "Does a thing",
  inputSchema: z.object({ pageId: z.string() }),
  outputSchema: z.object({ result: resultUnion }),
  execute: async () => ({ result: { type: "ok" as const, pageId: "x" } }),
})

// Same rule applies to inputSchema — arguably even more strictly,
// since clients use it to render tool params to the model.

mcptypescriptaimastra

lubosmatoMay 20, 2026