Implement remote upstream MCP transport and session lifecycle

[davidruzicka]

Summary

Implement a remote upstream MCP client for streamable HTTP and bind it to downstream MCP sessions managed by mcp4openapi.

Why

Proxy mode needs a real upstream client/session layer. Local request handling alone is not enough once tool discovery and tool execution come from a remote MCP server.

Deliverables

• Create a per-session upstream connection manager for remote MCP providers.
• Initialize the upstream session during downstream initialize handling.
• Reuse or adapt the current HTTP transport/session lifecycle so upstream sessions are cleaned up deterministically when downstream sessions end.
• Proxy downstream requests such as tools/list and tools/call to the upstream provider where appropriate.
• Add bounded timeouts and degraded failure handling for unavailable upstream servers.

Acceptance criteria

• A configured remote upstream MCP server can be initialized through mcp4openapi.
• Session creation and cleanup are deterministic and covered by tests.
• Tool requests are forwarded upstream with structured error mapping for timeout/auth/unavailable cases.
• The first iteration works without stdio support.

Suggested files

• src/mcp/mcp-server.ts
• src/transport/http-transport.ts
• src/core/errors.ts
• new provider/client modules under src/

Agent-authored issue.

[github-actions]

🤖 Agent note (issuer)

Autonomy gate decision: unsafe
Reasons:

• issue includes explicit acceptance or validation structure
• issue matches high-risk keywords that should stay in a human lane

[m13v]

We run an MCP server for macOS desktop automation and the session lifecycle cleanup was one of the trickiest parts to get right. A few things that bit us: Make sure upstream session teardown is idempotent - if the downstream client disconnects abruptly (which happens a lot with browser-based clients), you can get double-cleanup attempts that throw. We added a session state machine with explicit states like initializing, active, draining, closed, and only allow transitions in one direction. For timeouts on upstream requests, we use a two-tier approach. A short timeout (5s) for tools/list since that should be fast, and a longer one (30s) for tools/call since execution can take a while. The structured error mapping is important too, we found it helpful to distinguish between upstream-unavailable, upstream-timeout, and upstream-auth-failed so the downstream client can decide whether to retry or surface the error.

[m13v]

Our MCP server implementation handles similar session lifecycle and tool proxying concerns for desktop automation. Might be useful reference for the transport and error handling patterns: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/src/server.rs

[davidruzicka]

@m13v Hi Matthew, the state machine idea makes a lot of sense - we've been thinking about session teardown but hadn't considered the double-cleanup scenario from abrupt disconnects. Good catch.

The two-tier timeout split is also something we'd have probably gotten wrong initially (a single timeout for everything is the obvious first attempt).

Checking out the terminator repo now, thanks.

David

[m13v]

The double-cleanup from abrupt disconnects is surprisingly common in production. The other scenario to watch for: client reconnects before the server-side cleanup timer fires. You end up with the old session's cleanup racing against the new session's initialization. We solved it with a session generation counter - each new connection increments the generation, and cleanup only proceeds if the generation hasn't changed since the timer was set.

For the two-tier timeout, the specific values that worked for us: 30s for the "idle but connected" tier (covers network hiccups and temporary client pauses), and 5 minutes for the "disconnected, waiting for reconnect" tier. The gap between them matters more than the absolute values. Too close together and you get premature cleanup. Too far apart and you leak resources.

Sounds like you're on a solid track with the implementation.