feat(mcp): type mcp block replies from declared output schemas

MCP servers may declare an outputSchema on a tool and return
structuredContent, but discovery copied only name, description and
inputSchema, so no surface showed a reply shape and the MCP block declared
only content. Agents building workflows guessed field names, and a
reference such as <mcp.structuredContent.x> failed validation even when the
tool returned it.

- Discovery keeps a declared outputSchema on McpTool; the tool cache carries
  it, and managed connections persist it in the existing mcp_tools jsonb
  snapshot (type only, no migration).
- Surfaced on GET /api/v2/mcp-servers/{id}/tools (and so the CLI's
  mcp-servers tools list), mcp_list_operations, the editor tool list, and the
  integration catalog (synced contract, optional field). The v2 tool shape is
  strict, so keeping the field without declaring it would have turned
  discovery into a 500.
- The MCP block gains a hidden, server-managed toolOutputSchema sub-block: a
  structure-only snapshot of the selected operation's schema, bound to the
  server and operation it was taken for. The editor writes it when an
  operation is picked; applyWorkflowOperations writes it for agent edits,
  through the same authorized discovery use cases, best effort and only when
  the snapshot is missing or stale.
- With a matching snapshot, the block declares a typed structuredContent
  output beside content, so the run's reference check, lint (which now walks
  paths below structuredContent and names the declared fields) and the tag
  paths all read the declared shape, and workflows deps fills mock leaves
  from it. Without one, outputs are exactly as before.

Author: waleedlatif1

apps/docs/openapi-v2-resources.json

@@ -15190,6 +15190,39 @@
             },
             "description": "JSON Schema for the tool's arguments, as reported by the server."
           },
+          "outputSchema": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "object",
+                "description": "JSON Schema type of the structured result. MCP requires `object`."
+              },
+              "properties": {
+                "description": "Result field schemas keyed by field name.",
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {
+                  "description": "Server-defined JSON Schema for one result field."
+                }
+              },
+              "required": {
+                "description": "Names of the fields every result carries.",
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "description": "Name of a field every result carries."
+                }
+              }
+            },
+            "required": ["type"],
+            "additionalProperties": {
+              "description": "Additional JSON Schema keyword reported by the server."
+            },
+            "description": "JSON Schema for the tool's `structuredContent`, as reported by the server. Absent when the tool declares none."
+          },
           "serverId": {
             "type": "string",
             "description": "Identifier of the MCP server exposing the tool."

apps/sim/app/api/v2/mcp-servers/[mcpServerId]/tools/route.test.ts

@@ -232,6 +232,34 @@ describe('/api/v2/mcp-servers/[mcpServerId]/tools', () => {
     })
   })
 
+  /**
+   * The v2 tool shape is strict, so a discovered field the contract does not
+   * declare turns discovery into a 500 rather than being dropped. A declared
+   * `outputSchema` is server-authored below its `object` wrapper, like
+   * `inputSchema`, and passes through untouched.
+   */
+  it('publishes the output schema a tool declares', async () => {
+    const outputSchema = {
+      type: 'object' as const,
+      description: null,
+      properties: { hits: { type: 'array', items: { type: 'string' } } },
+      required: ['hits'],
+    }
+    mockDiscoverMcpServerToolsUseCase.mockResolvedValueOnce({
+      tools: [
+        { ...TOOL, outputSchema },
+        { ...TOOL, name: 'ping' },
+      ],
+    })
+
+    const response = await GET(request(`workspaceId=${WORKSPACE_ID}`), { ...context })
+    const body = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(body.data[0].outputSchema).toEqual(outputSchema)
+    expect(body.data[1]).not.toHaveProperty('outputSchema')
+  })
+
   /**
    * `McpConnectionError` interpolates the server's display name into its
    * message, so selecting the 503 wording by searching that message for

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/mcp-server-modal/mcp-tool-selector.tsx

@@ -2,6 +2,10 @@
 
 import { useMemo } from 'react'
 import { Combobox } from '@sim/emcn'
+import {
+  createMcpToolOutputSnapshot,
+  MCP_TOOL_OUTPUT_SCHEMA_SUBBLOCK,
+} from '@/lib/mcp/output-schema'
 import { useWorkflowScope } from '@/app/workspace/[workspaceId]/providers/workflow-scope-provider'
 import { formatDisplayText } from '@/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/formatted-text'
 import { getWorkflowSearchLabelHighlight } from '@/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/workflow-search-highlight'
@@ -35,6 +39,7 @@ export function McpToolSelector({
 
   const [storeValue, setStoreValue] = useSubBlockValue(blockId, subBlock.id)
   const [, setSchemaCache] = useSubBlockValue(blockId, '_toolSchema')
+  const [, setOutputSchemaSnapshot] = useSubBlockValue(blockId, MCP_TOOL_OUTPUT_SCHEMA_SUBBLOCK)
 
   const { server: serverValue } = useMcpBlockConfig({ blockId, previewContextValues })
 
@@ -68,6 +73,11 @@ export function McpToolSelector({
     const matchedTool = availableTools.find((tool) => tool.name === value)
     setStoreValue(matchedTool?.name ?? value)
     setSchemaCache(matchedTool?.inputSchema ?? null)
+    setOutputSchemaSnapshot(
+      matchedTool && typeof serverValue === 'string'
+        ? createMcpToolOutputSnapshot(serverValue, matchedTool.name, matchedTool.outputSchema)
+        : null
+    )
   }
 
   const handleOpenChange = (isOpen: boolean) => {

apps/sim/blocks/blocks/mcp.ts

@@ -1,4 +1,5 @@
 import { McpIcon } from '@/components/icons'
+import { MCP_TOOL_OUTPUT_SCHEMA_SUBBLOCK } from '@/lib/mcp/output-schema'
 import type { BlockConfig } from '@/blocks/types'
 import { IntegrationType } from '@/blocks/types'
 import type { ToolResponse } from '@/tools/types'
@@ -123,6 +124,15 @@ export const McpBlock: BlockConfig = {
       },
       dependsOn: ['tool'],
     },
+    {
+      id: MCP_TOOL_OUTPUT_SCHEMA_SUBBLOCK,
+      title: 'Output schema',
+      type: 'code',
+      hidden: true,
+      hideFromCopilot: true,
+      description:
+        "The selected operation's declared reply shape, which types the structuredContent output",
+    },
   ],
   tools: {
     access: ['mcp_run_operation', 'mcp_list_operations'],
@@ -157,7 +167,8 @@ export const McpBlock: BlockConfig = {
     serverId: { type: 'string', description: 'The supplied MCP server or connection ID' },
     operations: {
       type: 'json',
-      description: 'Authorized operations (name, description, inputSchema)',
+      description:
+        'Authorized operations (name, description, inputSchema, outputSchema if declared)',
     },
     nextCursor: { type: 'string', description: 'Cursor for the next page, or null' },
     hasMore: { type: 'boolean', description: 'Whether more authorized operations are available' },

apps/sim/executor/utils/block-reference.ts

@@ -101,7 +101,8 @@ function isOpaqueSchemaNode(value: unknown): boolean {
   return false
 }
 
-function isPathInSchema(schema: OutputSchema | undefined, pathParts: string[]): boolean {
+/** Whether `pathParts` names a field the declared output schema has, the check a run makes. */
+export function isPathInSchema(schema: OutputSchema | undefined, pathParts: string[]): boolean {
   if (!schema || pathParts.length === 0) {
     return true
   }

apps/sim/hooks/mcp/use-mcp-tools.ts

@@ -28,6 +28,7 @@ export interface McpToolForUI {
   serverName: string
   type: 'mcp'
   inputSchema: McpToolSchema
+  outputSchema?: McpToolSchema
   bgColor: string
   icon: ComponentType<SVGProps<SVGSVGElement>>
 }
@@ -55,6 +56,7 @@ export function useMcpTools(workspaceId: string): UseMcpToolsResult {
       serverName: tool.serverName,
       type: 'mcp' as const,
       inputSchema: tool.inputSchema,
+      outputSchema: tool.outputSchema,
       bgColor: getManagedMcpConnectorBgColor(tool.managedConnectorId) ?? '#6366F1',
       icon: tool.managedConnectorId ? getManagedMcpConnectorIcon(tool.managedConnectorId) : McpIcon,
     }))

apps/sim/lib/api/contracts/mcp.ts

@@ -97,6 +97,11 @@ export const mcpToolSchema = z.object({
   name: z.string(),
   description: z.string().optional(),
   inputSchema: mcpToolInputSchema,
+  /** Server-authored below the `object` wrapper; passed through as discovered. */
+  outputSchema: z
+    .object({ type: z.literal('object') })
+    .passthrough()
+    .optional(),
   serverId: z.string(),
   canonicalServerId: z.string().optional(),
   serverName: z.string(),

apps/sim/lib/api/contracts/v2/mcp-servers.ts

@@ -332,12 +332,38 @@ const v2McpToolInputSchema = z
   .catchall(z.unknown().describe('Additional JSON Schema keyword reported by the server.'))
   .describe("JSON Schema for the tool's arguments, as reported by the server.")
 
+/**
+ * The shape of a tool's `structuredContent`, as the MCP server reports it.
+ * Published open below the `object` wrapper for the reasons given for
+ * {@link v2McpToolInputSchema}; the SDK's `ToolSchema.outputSchema` pins the same
+ * three keys.
+ */
+const v2McpToolOutputSchema = z
+  .object({
+    type: z
+      .literal('object')
+      .describe('JSON Schema type of the structured result. MCP requires `object`.'),
+    properties: z
+      .record(z.string(), z.unknown().describe('Server-defined JSON Schema for one result field.'))
+      .optional()
+      .describe('Result field schemas keyed by field name.'),
+    required: z
+      .array(z.string().describe('Name of a field every result carries.'))
+      .optional()
+      .describe('Names of the fields every result carries.'),
+  })
+  .catchall(z.unknown().describe('Additional JSON Schema keyword reported by the server.'))
+  .describe(
+    "JSON Schema for the tool's `structuredContent`, as reported by the server. Absent when the tool declares none."
+  )
+
 /** One tool exposed by a registered MCP server. */
 export const v2McpToolSchema = z
   .object({
     name: z.string().describe('Tool name, as the MCP server reports it.'),
     description: z.string().optional().describe('Tool description reported by the server.'),
     inputSchema: v2McpToolInputSchema,
+    outputSchema: v2McpToolOutputSchema.optional(),
     serverId: z.string().describe('Identifier of the MCP server exposing the tool.'),
     serverName: z.string().describe('Display name of the MCP server exposing the tool.'),
   })

apps/sim/lib/credential-groups/mcp-oauth.ts

@@ -15,6 +15,7 @@ import {
 } from '@/lib/mcp/oauth'
 import { ManagedMcpOauthProvider } from '@/lib/mcp/oauth/managed-provider'
 import { mcpService } from '@/lib/mcp/service'
+import { toManagedMcpToolSnapshots } from '@/lib/mcp/tool-snapshot'
 
 export async function startCredentialGroupMcpOAuth(
   context: CredentialGroupMcpOAuthContext,
@@ -118,11 +119,7 @@ export async function completeCredentialGroupMcpOAuth(
     mcpServerId: context.server.id,
     mcpServerName: context.server.name,
     tokens: grantedTokens,
-    tools: tools.map((tool) => ({
-      name: tool.name,
-      ...(tool.description ? { description: tool.description } : {}),
-      inputSchema: tool.inputSchema,
-    })),
+    tools: toManagedMcpToolSnapshots(tools),
   })
   return { ...completion, mcpServerId: context.server.id }
 }

apps/sim/lib/credentials/application/discover-managed-mcp-tools.test.ts

@@ -201,6 +201,33 @@ describe('discoverManagedMcpToolsUseCase', () => {
       }),
     ])
   })
+  it('persists a declared output schema with the snapshot a connection lists from', async () => {
+    const outputSchema = { type: 'object' as const, properties: { hits: { type: 'array' } } }
+    mocks.discoverTools.mockResolvedValueOnce([
+      {
+        name: 'search_transcripts',
+        inputSchema: { type: 'object', properties: {} },
+        outputSchema,
+        serverId: context.mcpServerId,
+        serverName: context.mcpServerName,
+      },
+      {
+        name: 'ping',
+        inputSchema: { type: 'object' },
+        serverId: context.mcpServerId,
+        serverName: context.mcpServerName,
+      },
+    ])
+    await discoverManagedMcpToolsUseCase.execute({
+      principal,
+      input: { workspaceId: context.workspaceId, credentialId: context.credentialId },
+    })
+    expect(hoisted.saveToolSnapshot.mock.calls[0]?.[1]).toEqual([
+      { name: 'search_transcripts', inputSchema: { type: 'object', properties: {} }, outputSchema },
+      { name: 'ping', inputSchema: { type: 'object' } },
+    ])
+  })
+
   it.each(['draft', 'deployment'] as const)(
     'catalog preserves managed executor authority and %s operation policy',
     async (mode) => {