tools-only ADR-0003: Expose Multi-Transport Endpoints (HTTP / WebSocket / SSE / STDIO)
- Status: Accepted
- Date: 2025-02-01
- Deciders: Mihai Criveti
Context
ContextForge must serve diverse clients: web browsers, CLIs, language-specific SDKs, and headless daemons. Different use cases require support for both request/response and streaming interactions.
Requirements:
- Human-readable RPC over HTTP for developers
- Low-latency streaming for long-running tools
- IPC-style invocations for local CLI integration
- Unified business logic regardless of transport
Decision
The gateway will support the following built-in transports:
- HTTP JSON-RPC (primary RPC interface)
- WebSocket (bidirectional messaging)
- SSE (Server-Sent Events) (for push-only event streaming)
- Streamable HTTP (bidirectional, resumable streams, efficient MCP transport over HTTP)
- STDIO (optional local CLI / subprocess transport)
Transport selection is dynamic, based on environment (TRANSPORT_TYPE) and route grouping. All transports share the same service layer and authentication mechanisms.
Consequences
- ✅ Maximum client flexibility, supporting modern browsers and legacy CLI tools.
- 🔄 Business logic remains decoupled from transport implementation.
- 📶 Streaming transports (WS, SSE) require timeout, reconnection, and back-pressure handling. Easy expansion with new MCP standards
Alternatives Considered
| Option | Why Not |
|---|---|
| HTTP-only JSON API | Poor fit for long-lived streaming tasks; requires polling. |
| gRPC (HTTP/2) | Not browser-friendly; requires generated stubs; less discoverable. |
| Separate microservices per transport | Code duplication, diverging implementations, and operational complexity. |
| Single transport abstraction | Reduces explicitness; transport-specific needs get buried in generic interfaces. |
Status
All four transports are implemented in the current FastAPI application and are toggleable via configuration.