René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[FEATURE] MCP tools return empty result sets on upstream HTTP errors instead of erroring","articleBody":"## Summary\n\nWhen a provider API call fails (401/403/404/429/5xx), `run_select_query`\nover MCP returns a successful tool result with `{\"rows\": []}`. The HTTP\nfailure is only visible on the server process's stderr. MCP clients cannot\ndistinguish \"query ran, zero rows\" from \"query failed\", and absence-based\nchecks (e.g. compliance controls of the form \"this query must return no\nrows\") silently false-pass.\n\nThis is fixable entirely within stackql/stackql - any-sdk already returns\nthe erroneous response to the caller (see analysis below).\n\n## Reproduction\n\nExhaust the unauthenticated GitHub rate limit (60 req/h/IP), then via MCP\nstdio with `--auth='{\"github\": {\"type\": \"null_auth\"}}'`:\n\n~~~json\n{\"name\": \"run_select_query\", \"arguments\": {\"sql\": \"SELECT name FROM github.repos.repos WHERE org = 'stackql'\"}}\n~~~\n\nServer stderr shows:\n\n~~~text\nhttp response status code: 403, response body: {\"message\":\"API rate limit exceeded for ...\"}\n~~~\n\nbut the tool result is `isError: false` with `structuredContent.rows: []`\nand a \"**no results**\" markdown rendering. Observed on v0.10.500.\n\n## Analysis\n\n- any-sdk's HTTP layer (`internal/anysdk/client.go`,\n  `parseReponseBodyIfErroneous`) logs the error body to stderr but returns\n  the full non-2xx `*http.Response` to stackql with the body re-buffered -\n  the status code and body are available downstream. No any-sdk change is\n  required.\n- The swallow points are in\n  `internal/stackql/execution/mono_valent_execution.go`:\n  - the plain-select path returns success with a nil payload on erroneous\n    responses:\n\n    ~~~go\n    if httpResponse.StatusCode \u003e= 300 {\n        return newHTTPProcessorResponse(nil, reversalStream, false, nil)\n    }\n    ~~~\n\n  - similarly, `res.HasError()` routes the error text into the message\n    handler and returns a nil error.\n\n  By contrast the `isMaterialiseResponse` branch already generates an\n  error for `StatusCode \u003e= 400`, so mutations/materialised ops surface\n  failures - it is specifically selects that degrade to empty results.\n- `internal/stackql/mcpbackend.extractQueryResults` already checks\n  `resp.GetError()` and would propagate a populated error; today it can\n  only ever produce the opaque `failed to extract query results`.\n\n## Proposed fix (two layers, both in this repo)\n\n1. **Execution**: in the select path of `mono_valent_execution.go`, treat\n   `StatusCode \u003e= 400` as an error (mirroring the materialise branch),\n   carrying status code and response body into the `ExecutorOutput` error\n   instead of returning `(nil payload, nil error)`.\n2. **MCP surface** (`pkg/mcp_server`): map backend errors to\n   `CallToolResult` with `isError: true` and a structured error payload in\n   the text/structured content, including a retryability classification:\n\n   ~~~json\n   {\n     \"error\": {\n       \"message\": \"GET https://api.github.com/... failed\",\n       \"http_status\": 403,\n       \"provider\": \"github\",\n       \"retryable\": false\n     }\n   }\n   ~~~\n\n   Suggested classification: 408/429/5xx retryable; 400/401/403/404 not\n   (with 403-rate-limit bodies ideally classified as retryable, since\n   GitHub uses 403 for rate limiting).\n\n## Impact\n\nAny MCP client running absence-based checks gets false negatives today.\nThe interim mitigation we ship in auditron (stackql-mcp-rs demo) is a\ncanary control (`SELECT` that must return rows) whose failure flags a\nbroken run - workable, but it shouldn't be necessary, and it cannot\nattribute the failure or advise on retry.\n","author":{"url":"https://github.com/jeffreyaven","@type":"Person","name":"jeffreyaven"},"datePublished":"2026-06-13T01:11:16.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/670/stackql/issues/670"}