paperclipai/paperclip · error · ToolGatewayHttpError

mcp_remote_fetch_failed

mcp_remote_fetch_failed

Error message

Remote MCP tool call failed

What it means

Catch-all in the remote MCP call path: the fetch or response handling threw a non-ToolGatewayHttpError, non-timeout exception (DNS failure, socket reset, unexpected parser crash). Connection health is marked error and the error propagates as a gateway 502 with execution details attached for diagnosis.

Source

Thrown at server/src/services/tool-gateway.ts:3244

      summary: grantKind === "organization"
        ? "Organization authorization is required before this run can continue."
        : "Personal authorization is required before this run can continue.",
      createdByAgentId: session.agentId,
      addresseeUserId: userId,
      payload,
    });
  }

  async function resolveConnectionGrant(
    session: ToolGatewaySession,
    connection: typeof toolConnections.$inferSelect,
  ): Promise<typeof connectionGrants.$inferSelect> {
    const [run] = session.runId && !session.identityContextId
      ? await db.select({
          responsibleUserId: heartbeatRuns.responsibleUserId,
          invocationSource: heartbeatRuns.invocationSource,
        }).from(heartbeatRuns).where(and(
          eq(heartbeatRuns.id, session.runId),
          eq(heartbeatRuns.companyId, session.companyId),
        )).limit(1)
      : [];
    const actingUserId = session.identityContextId ? session.responsibleUserId ?? null : run?.responsibleUserId ?? session.responsibleUserId ?? null;
    if (session.identityContextId && session.agentId && (
      connection.config.sourceTemplateKey === "github" || connection.transportConfig?.sourceTemplateKey === "github"
    )) {
      const captured = githubOperationCredentials.get(session);
      const selected = captured
        ? { grant: captured.grant, error: undefined }
        : await resolveManagedGitHubIdentitySelection(db, session.companyId, {
          agentId: session.agentId, responsibleUserId: session.responsibleUserId, allowStandingDelegation: false,
        });
      if (!selected.grant || selected.grant.connectionId !== connection.id) {
        throw new ToolGatewayHttpError(409, selected.error ?? "GitHub identity changed; retry through the managed tool", "github_identity_unavailable");
      }
      if (selected.grant.kind === "user") {
        const [member] = await db.select({ role: companyMemberships.membershipRole }).from(companyMemberships).where(and(

View on GitHub (pinned to 01ad858492)

Solutions

1. The remote MCP call failed at the transport level. Check network connectivity and remote server status, then retry.

When it happens

Trigger: Thrown at server/src/services/tool-gateway.ts:3166 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/9b85b5ca2bf8d650. Report an issue: GitHub.