Fix(mcp): improve remote HTTP transport compatibility

Author: kesimo

CHANGELOG.md

@@ -7,6 +7,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.21.18] - 2026-05-28
+
+### Fixed
+
+- **Remote MCP HTTP compatibility** - HTTP MCP endpoints without an explicit transport now try Streamable HTTP first and fall back to legacy SSE only when the connection fails before initialization, improving compatibility with stricter SSE servers while preserving explicit `type` settings and per-server headers.
+- **MCP transport config compatibility** - existing MCP configs and management clients can continue using legacy `transport` fields and values such as `sse/http` or `streamable-http`, which are now normalized to Facio's canonical transport settings during config load.
+- **Placet review message ordering** - active Placet response streams are now closed before review prompts are sent, keeping approval and HITL messages ordered separately from the draft assistant stream.
+
 ## [0.21.17] - 2026-05-27
 
 ### Fixed

facio/agent/loop.py

@@ -34,6 +34,7 @@
     RUNTIME_CHECKPOINT_KEY,
     SessionCheckpointManager,
 )
+from facio.agent.stream_boundary import reset_stream_boundary_hook, set_stream_boundary_hook
 from facio.agent.stream_session import StreamSession
 from facio.agent.subagent import SubagentManager
 from facio.agent.tools.file_state import FileStateStore, bind_file_states, reset_file_states
@@ -1055,6 +1056,7 @@ async def _dispatch(self, msg: InboundMessage) -> None:
         )
         _run_status: dict[str, Any] = {}
         _run_t0 = time.monotonic()
+        _stream_boundary_token = set_stream_boundary_hook(None)
 
         lock = self._session_locks.setdefault(session_key, asyncio.Lock())
         gate = self._concurrency_gate or nullcontext()
@@ -1096,6 +1098,10 @@ async def _dispatch(self, msg: InboundMessage) -> None:
                             mt, "set_pre_send_hook"
                         ):
                             mt.set_pre_send_hook(stream.finalize_and_rotate)
+                        reset_stream_boundary_hook(_stream_boundary_token)
+                        _stream_boundary_token = set_stream_boundary_hook(
+                            stream.finalize_and_rotate
+                        )
 
                 # Send immediate "Thinking" progress so the frontend shows
                 # an indicator before the LLM call starts.
@@ -1167,6 +1173,7 @@ async def _dispatch(self, msg: InboundMessage) -> None:
                     # Restore active status after processing
                     await self._runtime.send_status(agent_status.ACTIVE)
         finally:
+            reset_stream_boundary_hook(_stream_boundary_token)
             self._runtime.discard_rotator(session_key)
             # Clear the pre-send hook we may have installed on MessageTool
             # so the next (possibly non-streaming) turn starts with a clean

facio/agent/stream_boundary.py

@@ -0,0 +1,38 @@
+"""Context-local stream boundary hook for user-visible side messages.
+
+Tools that emit their own Placet messages while the model is streaming need
+to close the current draft before they send, then let the agent loop rotate to
+a fresh stream id. This keeps the chat timeline ordered without coupling each
+tool to ``AgentLoop`` or ``StreamSession`` directly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from contextvars import ContextVar, Token
+
+StreamBoundaryHook = Callable[[], Awaitable[None]]
+
+_HOOK: ContextVar[StreamBoundaryHook | None] = ContextVar(
+    "facio_stream_boundary_hook",
+    default=None,
+)
+
+
+def set_stream_boundary_hook(hook: StreamBoundaryHook | None) -> Token[StreamBoundaryHook | None]:
+    """Set the hook for the current execution context."""
+    return _HOOK.set(hook)
+
+
+def reset_stream_boundary_hook(token: Token[StreamBoundaryHook | None]) -> None:
+    """Restore the previous hook for the current execution context."""
+    _HOOK.reset(token)
+
+
+async def finalize_and_rotate_current_stream() -> bool:
+    """Run the active stream boundary hook, if this context has one."""
+    hook = _HOOK.get()
+    if hook is None:
+        return False
+    await hook()
+    return True

facio/agent/tools/manage_mcp.py

@@ -26,13 +26,20 @@
         ),
         config=StringSchema(
             "JSON string with server config (required for 'add'). "
-            "Fields: command, args, env, url, headers, tool_timeout, enabled_tools. "
-            "Example: {\"command\": \"npx\", \"args\": [\"-y\", \"@example/mcp-server\"]}",
+            "Fields: command, args, env, url, type, headers, tool_timeout, enabled_tools, enabled. "
+            "For ambiguous HTTP endpoints, omit type to allow automatic streamableHttp then SSE fallback. "
+            "Set type to 'sse' or 'streamableHttp' only to force a transport. "
+            "Headers remain per-server; for example "
+            "{\"url\": \"https://example.com/mcp\", "
+            "\"headers\": {\"Authorization\": \"Bearer ...\"}}. "
+            "Stdio example: {\"command\": \"npx\", \"args\": [\"-y\", \"@example/mcp-server\"]}",
             nullable=True,
         ),
         updates=StringSchema(
             "JSON string with fields to update (for 'edit'). "
-            "Example: {\"tool_timeout\": 60, \"enabled_tools\": [\"*\"]}",
+            "Use this for targeted per-server compatibility overrides such as "
+            "{\"type\": \"sse\", \"headers\": {\"Accept\": \"text/event-stream\"}} "
+            "or {\"tool_timeout\": 60, \"enabled_tools\": [\"*\"]}.",
             nullable=True,
         ),
         confirmed=StringSchema(
@@ -67,6 +74,8 @@ def description(self) -> str:
             "'edit' updates server config (requires name + updates JSON), "
             "'enable'/'disable' toggles a server on/off, "
             "'restart' reconnects a server. "
+            "For HTTP MCP compatibility, leave type unset for automatic streamableHttp/SSE fallback "
+            "or use per-server type and headers to force one transport. "
             "For credentials, use the separate 'manage_credentials' tool."
         )