MCP Tool Schema Design#

Every MCP tool in Langfuse uses a deliberate two-schema pattern to decouple what is advertised to MCP clients from what is enforced at runtime. This pattern is defined in defineTool and applied consistently across all prompt tools.

The baseSchema / inputSchema Split#

The DefineToolOptions interface requires two separate Zod schemas:

Inside defineTool, baseSchema is converted using Zod v4's native z.toJSONSchema with target: "draft-7" and unrepresentable: "any". The resulting JSON Schema object is what MCP clients (Claude Code, Cursor, etc.) receive when they discover the tool. The inputSchema.parse(rawInput) call in the wrapped handler is what actually gates execution.

Why the Split Exists: JSON Schema Union-Type Incompatibility#

MCP clients auto-render tool input forms from the JSON Schema they receive. Zod schemas that contain union types (.union(), .discriminatedUnion(), .superRefine()) serialize to oneOf/anyOf in JSON Schema. Some MCP clients mishandle or ignore these union alternatives when rendering array-item forms, causing incorrect UI or silent validation failures.

The workaround is to keep baseSchema flat and free of Zod refinements — using simple, portable types that serialize cleanly — and push all complex validation into inputSchema, which runs server-side only 3.

Concrete Example: createChatPrompt#

The createChatPrompt tool (source) illustrates both schemas in the same file:

• CreateChatPromptBaseSchema uses plain z.string() and z.array(z.object({role, content})). Comment explicitly notes: "Using simple object schema instead of union to comply with MCP spec" 4.
• CreateChatPromptInputSchema replaces those with stricter validators from @langfuse/shared (PromptNameSchema, PromptLabelSchema) and additional error messages.

PR #13323 extended this tool to support placeholder messages (a {type: "placeholder", name} shape alongside {role, content} messages). Rather than introduce a oneOf in baseSchema, it added a flat ChatMessageBaseSchema with all four fields optional, and moved the either/or constraint into inputSchema via .superRefine().

Pattern Usage Across Tools#

The split is applied uniformly across the mcp/features/prompts/tools directory:

Key Files#

Authoring a New Tool#

When adding a new MCP tool:

1. Write baseSchema first — use only simple Zod types (z.string(), z.number(), z.array(z.object(...))) with no .refine() or .superRefine(). Avoid union types in array items.
2. Write inputSchema separately — extend or replace fields with stricter validators from @langfuse/shared and add all cross-field refinements.
3. Pass both to defineTool 5. The framework handles JSON Schema generation and runtime validation wiring automatically.
4. If a field's domain type (e.g., PromptNameSchema) would produce oneOf/anyOf in JSON Schema, substitute a plain z.string() in baseSchema and rely on inputSchema for the domain constraint.