Skip to content

Return correlated errors for hosted MCP gateway failures - #328

Merged
khaliqgant merged 3 commits into
AgentWorkforce:mainfrom
miyaontherelay:fix/hosted-mcp-gateway-errors
Nov 19, 2026
Merged

khaliqgant merged 3 commits into
AgentWorkforce:mainfrom
miyaontherelay:fix/hosted-mcp-gateway-errors

Conversation

@miyaontherelay

@miyaontherelay miyaontherelay commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

A hosted MCP call can receive an empty HTTP 5xx when the application Worker terminates before its handler can respond. The gateway currently forwards that response unchanged, leaving clients with an empty transport error.

Wrap the existing router dispatch for canonical-host MCP POST endpoints. Uncorrelated 5xx responses and thrown dispatch failures now return a safe JSON-RPC message with a correlation ID in the body and header. Fixed-category logs join that ID to the validated platform request ID. Application-correlated errors and successful streams pass through unchanged; maintenance responses retain their original body and retry contract. Calls are forwarded once, without reading or replaying their request bodies. This improves diagnostics outside the application isolate; it does not fix the underlying memory allocation.

Validation at 2da8353b7051c9fb73fa730154627067dc7d8193:

  • npm --workspace router run test: 344 tests across 13 files. Removing the outer dispatch wrapper makes 13 integration assertions fail, including empty failures, thrown dispatch, maintenance preservation and correlation behavior.
  • npm run typecheck: both web and router typechecks pass.
  • npm run lint: zero errors; four warnings in unchanged web files.
  • Local esbuild bundle of router/index.ts: succeeds (53,615 bytes).
  • Exact-head GitHub CI: both Tests and typecheck and Typecheck, lint, test, build pass, including the full web/router suites and production build. Independent reviewer SHIP is posted on this commit; automated checks alone are not review approval.
  • Full npm test: the web suite has two unchanged path-encoding fixture failures when the checkout path contains a space (635/637); the router suite passes. The fixtures use URL pathname text as a shell path; decoding the path resolves their syntax/help probes. No web source or test was changed.

Opened from a fork so the existing same-repository preview guard skips deployment. No routing flags, infrastructure, credentials or workflows change. Keep merge-train:hold until owner approval; no merge or deployment is requested.

@miyaontherelay miyaontherelay added the merge-train:hold Do not merge without Khaliq's direct OK label Nov 19, 2026
@composalagent

composalagent Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Composal Verify · PR #328

Skipped Skipped · commit 2da8353b7051

Warning

This request is merged; previous verification results remain in the history.

Backend-only diff: automatic browser tests were skipped. Relevant scenarios are available to run manually against the configured test environment.

Diff assessment: Adds server-side MCP gateway error handling for POST requests: correlated JSON-RPC errors for uncorrelated 5xx responses and dispatch exceptions, diagnostic logging, and maintenance-response preservation. Changes include backend tests and documentation, with no frontend or browser-rendered modifications.

Why no scenarios were selected

No saved scenario matched this change.

Recent verification history
Commit Result Started
2da8353b7051 Skipped Skipped 2026-11-19 17:30 UTC

@coderabbitai

coderabbitai Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 42c6bd00-3b6e-439f-aeca-7f6d8c19781b
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@khaliqgant khaliqgant left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

neonexit-reviewer @ 2da8353: SHIP (router: correlated hosted-MCP gateway failures).

  • Scope: it applies only to POST on hostname agentrelay.com for /mcp, /api/v1/mcp/shared-sessions, /api/v1/mcp/relay-events and /api/v1/replicas/mcp (an optional /cloud prefix and trailing slash are normalized). Every other request goes through forward() exactly as before, including rethrowing on failure.
  • Never replays: forward() is called once. A thrown dispatch failure becomes a correlated 503 for these MCP paths only.
  • Untouched pass-through: any status below 500, and any 5xx that already carries x-correlation-id (which cloud's MCP diagnostics now add), is returned unread. Successful streams are never buffered.
  • The cutover contract is preserved. A 5xx carrying x-agent-relay-database-read-only: enabled (cloud's worker-read-only-cutover.mjs:110) or x-agent-relay-database-target: unavailable (worker-request-lifecycle.mjs:55 and the proactive runtime's worker.ts:158) is passed through with its body, status and every header, Retry-After included, plus only x-correlation-id and cache-control: no-store. Any other uncorrelated 5xx keeps its status and headers, including Retry-After, but gets a fixed JSON-RPC body. The upstream body is cancelled, not read, and content headers are dropped.
  • No PII: the log is {event, endpoint, status, correlationId, cfRay (format-validated, colo stripped), failure category}, with no URL, headers, bodies or exception text. The id is crypto.randomUUID().

What I ran (fresh worktree at 2da8353, npm ci):

Check Result
router: npm test 13 files, 344/344
router: npm run typecheck 0

Non-blocking: the hostname check is exact (agentrelay.com), so www. or any other alias won't get the fallback. That's fine if the apex is the only MCP host, as the README says.

@khaliqgant
khaliqgant merged commit d91fbb2 into AgentWorkforce:main Nov 19, 2026
5 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-train:hold Do not merge without Khaliq's direct OK

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants