{"record":{"id":"eda430b73b781d3f","repo":"ComposioHQ/composio","slug":"failed-to-parse-mcp-server-instance-eda430","errorCode":null,"errorMessage":"Failed to parse MCP server instance","messagePattern":"Failed to parse MCP server instance","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"ts/packages/core/src/models/MCP.ts","lineNumber":471,"sourceCode":"    };\n    const urlResponse = await withCancellation(\n      () => this.client.mcp.generate.url(urlBody, requestOptions),\n      requestOptions?.signal\n    );\n\n    const userIdsURL = urlResponse.user_ids_url[0];\n    const serverInstance = MCPServerInstanceSchema.safeParse({\n      id: server.id,\n      name: server.name,\n      type: 'streamable_http' as const,\n      url: userIdsURL,\n      userId: userId,\n      allowedTools: server.allowed_tools,\n      authConfigs: server.auth_config_ids,\n    });\n\n    if (serverInstance.error) {\n      throw new ValidationError('Failed to parse MCP server instance', {\n        cause: serverInstance.error,\n      });\n    }\n\n    return serverInstance.data;\n  }\n}\n","sourceCodeStart":453,"sourceCodeEnd":479,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/ts/packages/core/src/models/MCP.ts#L453-L479","documentation":"The MCP server instance returned by the backend did not match MCPServerInstanceSchema, so the SDK refused to parse it. This indicates an API/SDK contract mismatch or an unexpected response payload, not bad caller input.","triggerScenarios":"Calling the instance generate flow (result/text/server/mcp/instance helpers) where the server response fails schema validation — e.g. missing expected fields like allowed_tools or auth_config_ids, or renamed response keys after a backend change.","commonSituations":"Backend deployed a response shape newer than the SDK's pinned schema; using an outdated @composio/core against a changed API; proxies stripping fields from the response.","solutions":["Upgrade @composio/core to the latest version to pick up updated response schemas","Inspect error.cause (ZodError) to see which response fields are missing/invalid","If it persists, report the response shape to Composio with the Zod issues"],"exampleFix":"// before: @composio/core@3.x (old)\nconst inst = await mcp.server.instance(id);\n// after\npnpm add @composio/core@latest","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { const inst = await mcp.server.instance(id); } catch (e) { if (e instanceof ValidationError && /parse MCP server instance/.test(e.message)) { await upgradeSdkAndRetry(); return; } throw e; }","preventionTips":["Keep @composio/core updated alongside backend changes","Pin SDK versions deliberately and test after backend releases","Capture Zod causes in logs to speed diagnosis"],"tags":["mcp","response-parsing","zod","version-mismatch"],"backgroundTag":"response-schema-mismatch","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}