Real-Time Transport & MCP

Relevant source files

The following files were used as context for generating this wiki page:

• src/forze_socketio/server.py
• src/forze_socketio/emitter.py
• src/forze_mcp/server.py
• pyproject.toml
• CLAUDE.md
• skills/forze-fastapi-interface/SKILL.md

Real-Time Transport & MCP (Model Context Protocol) in Forze provides the infrastructure for bidirectional communication and AI-driven tool interaction. These integrations allow Forze handlers and domain aggregates to be exposed through modern real-time protocols such as Socket.IO and the Model Context Protocol, extending the framework's reach beyond traditional RESTful HTTP interfaces.

The system is designed to maintain the core architectural principles of Forze—specifically Hexagonal Architecture and Domain-Driven Design—by wrapping standard business logic in transport-specific adapters. This ensures that the underlying application logic remains decoupled from the specific communication protocol used, whether it be a persistent WebSocket connection or a standardized interface for AI agents.

Sources: CLAUDE.md, pyproject.toml:135-144

Socket.IO Integration

The Socket.IO integration provides a high-level abstraction for real-time, event-based communication. It allows the application to emit events to specific rooms or clients and handle incoming messages by dispatching them to the appropriate Forze handlers.

Server and Emitter Architecture

The architecture consists of a server-side component for managing connections and an emitter for outbound messaging. The SocketIOEmitter is a primary tool for pushing data to clients from within the application layer.

The diagram above illustrates how application handlers use the Emitter to broadcast messages through the infrastructure layer to connected clients.

Sources: src/forze_socketio/emitter.py, src/forze_socketio/server.py

Key Components

Component	Description	Source
SocketIOEmitter	Handles outbound event emission, room management (join/leave), and client disconnection.	src/forze_socketio/emitter.py
Namespace	Organizes Socket.IO logic into distinct communication channels.	src/forze_socketio/server.py
AsyncServer	The core Socket.IO server implementation for handling asynchronous connections.	src/forze_socketio/server.py

Event Emission and Management

The SocketIOEmitter provides a specialized interface for interacting with the Socket.IO server, particularly when using a Redis manager for multi-node deployments.

• Emission: Events can be emitted globally, to specific rooms, or to specific namespaces using the emit method.
• Room Management: The emitter provides enter_room and leave_room methods to manage client subscriptions to specific data streams.
• Session Control: Individual clients can be forcibly disconnected using the disconnect method.

Sources: src/forze_socketio/emitter.py:9-40

Model Context Protocol (MCP)

The Model Context Protocol (MCP) integration allows Forze aggregates and operations to be exposed as tools for AI models. This enables LLM-based agents to discover and invoke application functionality through a standardized interface.

Tool Exposure

Operations registered in the Forze OperationRegistry can be mapped to MCP tools. This mapping includes the translation of operation schemas into MCP-compatible formats, allowing agents to understand the required input parameters and expected return types.

The sequence diagram shows the discovery and execution flow where an AI agent interacts with Forze operations via the MCP Server.

Sources: src/forze_mcp/server.py, skills/forze-fastapi-interface/SKILL.md

Server Implementation

The forze_mcp package utilizes fastmcp to bridge the gap between Forze's internal execution engine and the MCP protocol. This server component handles the lifecycle of the MCP connection and the dispatching of tool calls to the underlying Forze handlers.

Sources: src/forze_mcp/server.py, pyproject.toml:144

Dependency and Lifecycle Management

Both Socket.IO and MCP integrations require specific dependencies and lifecycle hooks to be registered within the DepsRegistry and LifecyclePlan.

Configuration Options

Integration	Dependency Extras	Key Library
Socket.IO	socketio	python-socketio
MCP	mcp	fastmcp, mcp

Sources: pyproject.toml:135-144

Implementation Pattern

To integrate these transports, authors typically follow the Forze integration pattern:

1. Define Dependencies: Register transport-specific clients (e.g., AsyncServer or FastMCP) in a DepsModule.
2. Setup Lifecycle: Use lifecycle steps to start and stop the real-time servers alongside the main application.
3. Bind Operations: For MCP, operations are bound to the server; for Socket.IO, namespaces are defined to handle incoming events and route them to ExecutionContext.

Sources: CLAUDE.md, skills/forze-fastapi-interface/SKILL.md

Summary

Real-Time Transport & MCP in Forze extend the reach of domain logic to interactive and AI-driven environments. By utilizing forze_socketio, developers can build responsive, event-driven user interfaces. Simultaneously, the forze_mcp integration enables the creation of "AI-ready" backends where business operations are directly accessible to LLM agents as structured tools. Both systems adhere to Forze's core tenets of explicit boundaries and protocol-agnostic business logic.