MCP Integration Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) integration within the WIREDUP project provides a standardized framework for advanced AI communication. It enables structured messaging, context management, and tool-calling capabilities across different agents and services. This system acts as a specialized communication layer that ensures consistency in how AI models interact with the host environment and each other.
The integration facilitates high-level orchestration by providing a common protocol for requests, responses, notifications, and error handling. It is a core component of the Auto-Wiring system, allowing for intelligent dependency injection and standardized participation in multi-agent workflows.
Sources: src/mcp/protocol.py:1-12, README.md:12-25, AGENT.md:196-200
Protocol Architecture
The MCP system is built around several core components that manage the lifecycle of a conversation. The primary engine is the MCPProtocol class, which handles message routing, context persistence, and event hooks.
Core Components
| Component | Description |
|---|---|
MCPProtocol | The main implementation class responsible for session management, handler registration, and message dispatching. |
MCPMessage | A dataclass representing a single unit of communication, including metadata, role information, and content. |
MCPContext | Manages the state of a session, including message history, session variables, and metadata. |
MCPHandler | An interface for creating logic that processes specific types of incoming messages. |
Sources: src/mcp/protocol.py:73-205, src/mcp/protocol.py:44-70
Message Flow Lifecycle
When a message is processed through the MCP integration, it undergoes a series of hook executions and handler evaluations. This ensures that the system remains extensible and observable.
The diagram above illustrates the internal logic flow within the receive method of the protocol.
Sources: src/mcp/protocol.py:168-198
Data Structures and Models
Message Roles and Types
The protocol defines specific enums to categorize participants and communication types, ensuring that agents can interpret the intent of a message programmatically.
- MCPMessageType: Defines the nature of the message:
REQUEST,RESPONSE,NOTIFICATION,ERROR, orSTREAM. - MCPRole: Identifies the sender's role:
SYSTEM,USER,ASSISTANT,TOOL, orAGENT.
Sources: src/mcp/protocol.py:22-41
MCPMessage Schema
Messages are structured to support both simple text and complex data objects.
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier for the message. |
type | MCPMessageType | The category of the message. |
role | MCPRole | The role of the message sender. |
content | Union[str, Dict] | The actual payload of the message. |
parent_id | Optional[str] | Reference to a previous message (for threading/responses). |
metadata | Dict | Arbitrary data associated with the message. |
Sources: src/mcp/protocol.py:44-55
Implementation and Integration
Handler Registration
Handlers are the primary way to extend the protocol's functionality. A handler must implement can_handle to filter messages and handle to perform the logic.
class TaskHandler(MCPHandler):
def can_handle(self, message: MCPMessage, context: MCPContext) -> bool:
return message.type == MCPMessageType.REQUEST and message.content.get('type') == 'execute_task'
def handle(self, message: MCPMessage, context: MCPContext) -> MCPMessage:
task = message.content.get('task')
return MCPMessage(
id=f"resp_{message.id}",
type=MCPMessageType.RESPONSE,
role=MCPRole.ASSISTANT,
content={'result': f"Completed: {task}"},
parent_id=message.id
)
Sources: examples/mcp_integration.py:20-47
Context Management
MCPProtocol manages a MCPContext object that persists for the duration of a session. It supports exporting and importing state, which is critical for distributed agent systems.
The class diagram shows the relationship between the protocol engine, its context, and the messages it handles.
Sources: src/mcp/protocol.py:61-125, src/mcp/protocol.py:128-154
Tool and Function Calling
MCP supports standardized tool invocation. This allows an assistant to request an action (like a database query or web search) and receive a structured response back through the protocol.
- Tool Call: An
ASSISTANTrole sends aREQUESTmessage containing atool_callpayload. - Tool Execution: The system executes the requested function.
- Tool Response: A
TOOLrole sends aRESPONSEmessage with the result, linked viaparent_id.
Sources: src/mcp/protocol.py:207-248, AGENT.md:214-225
Event Hooks
The protocol provides several lifecycle hooks for observability and middleware-like functionality.
before_send/after_send: Executed during message dispatch.before_receive/after_receive: Executed during message intake.on_error: Executed when a handler or the protocol engine encounters an exception.
Sources: src/mcp/protocol.py:133-146, examples/mcp_integration.py:61-68
Conclusion
The MCP Integration is a robust communication layer that standardizes AI-to-System and AI-to-AI interactions within the WIREDUP project. By combining structured messaging, session-aware context, and extensible handlers, it enables the creation of complex, stateful multi-agent systems. Its integration with the project's Auto-Wiring core ensures that protocol instances and handlers can be dynamically injected and managed across the infrastructure.
Sources: README.md:43-58, src/mcp/protocol.py:120-125