ComposioHQ/composio · error · ValidationError

Failed to parse MCP server instance

Error message

Failed to parse MCP server instance

What it means

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.

Source

Thrown at ts/packages/core/src/models/MCP.ts:471

    };
    const urlResponse = await withCancellation(
      () => this.client.mcp.generate.url(urlBody, requestOptions),
      requestOptions?.signal
    );

    const userIdsURL = urlResponse.user_ids_url[0];
    const serverInstance = MCPServerInstanceSchema.safeParse({
      id: server.id,
      name: server.name,
      type: 'streamable_http' as const,
      url: userIdsURL,
      userId: userId,
      allowedTools: server.allowed_tools,
      authConfigs: server.auth_config_ids,
    });

    if (serverInstance.error) {
      throw new ValidationError('Failed to parse MCP server instance', {
        cause: serverInstance.error,
      });
    }

    return serverInstance.data;
  }
}

View on GitHub (pinned to 64b1b85502)

Solutions

1. Upgrade @composio/core to the latest version to pick up updated response schemas
2. Inspect error.cause (ZodError) to see which response fields are missing/invalid
3. If it persists, report the response shape to Composio with the Zod issues

Example fix

// before: @composio/core@3.x (old)
const inst = await mcp.server.instance(id);
// after
pnpm add @composio/core@latest

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; }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to parse MCP server instance
• experimental_subAgent() requires Zod 4 with z.toJSONSchema()
• Invalid parameters passed to create mcp config
• Failed to validate list options
• Failed to validate update params

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/eda430b73b781d3f. Report an issue: GitHub.