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.

Solutions

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

Strategy: try-catch

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@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/9b85b5ca2bf8d650. Report an issue: GitHub.

Appendix: source

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

          "Remote MCP tool call timed out.",
        );
        throw new ToolGatewayHttpError(
          504,
          "Remote MCP tool call timed out",
          "tool_timeout",
          {
            connectionId: connection.id,
            catalogEntryId: entry.id,
            execution,
          },
        );
      }
      await markRemoteConnectionHealth(
        connection,
        "error",
        "Remote MCP tool call failed.",
      );
      throw new ToolGatewayHttpError(
        502,
        "Remote MCP tool call failed",
        "mcp_remote_fetch_failed",
        {
          connectionId: connection.id,
          catalogEntryId: entry.id,
          execution,
        },
      );
    } finally {
      clearTimeout(timer);
    }
  }

  async function executeLocalStdioTool(
    session: ToolGatewaySession,
    tool: ToolGatewayDescriptor,
    parameters: unknown,

View on GitHub (pinned to 3f1d897a7c)