MCP Protocol Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) in WIREDUP is an advanced AI communication implementation designed to standardize how agents, tools, and systems interact. It facilitates structured message exchange, maintains conversation state through context management, and provides a robust framework for tool/function calling and event-driven hooks.
Within the broader architecture, MCP serves as a specialized communication layer between the Auto-Wiring core and AI agents, ensuring that data flow remains consistent whether an agent is performing research, executing code, or communicating with a user interface. It is essential for providing standardized AI infrastructure that supports complex orchestration and remote command execution.
Sources: src/mcp/protocol.py:6-15, README.md:12, public/index.html:138-145
Core Data Structures
The protocol relies on several primary data structures to represent messages and their surrounding context.
MCP Message Model
Every interaction in the protocol is encapsulated in an MCPMessage. These messages contain unique identifiers, type definitions, and roles to distinguish between different participants like system processes, users, or AI assistants.
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier for the message. |
type | MCPMessageType | The nature of the message (Request, Response, etc.). |
role | MCPRole | The entity sending the message (User, Assistant, Tool, Agent). |
content | Union[str, Dict] | The actual payload or text of the message. |
parent_id | Optional[str] | Link to a previous message to maintain threading. |
metadata | Dict[str, Any] | Additional context or configuration data. |
Sources: src/mcp/protocol.py:34-45, src/mcp/protocol.py:47-53
MCP Context and Session Management
The MCPContext class manages the state of a specific conversation or session. It tracks the message history and allows for the storage of session-specific variables that can be accessed by handlers during message processing.
The diagram shows the relationship between a session context and the messages it contains.
Sources: src/mcp/protocol.py:64-75, src/mcp/protocol.py:77-96
Architecture and Message Flow
The MCPProtocol class acts as the central router. It coordinates the registration of handlers and hooks, and manages the logic for sending and receiving messages.
Message Processing Pipeline
When a message is received, the protocol follows a strict sequence: executing "before" hooks, searching for a compatible handler, executing the handler logic, and finally triggering "after" hooks.
This flowchart illustrates the internal logic of the MCPProtocol.receive() method.
Sources: src/mcp/protocol.py:171-180, src/mcp/protocol.py:182-205
Messaging Enums
The protocol uses specific enumerations to categorize traffic and identify participants.
- MCPMessageType:
REQUEST,RESPONSE,NOTIFICATION,ERROR,STREAM. - MCPRole:
SYSTEM,USER,ASSISTANT,TOOL,AGENT.
Sources: src/mcp/protocol.py:21-31, src/mcp/protocol.py:110-120
Handlers and Extensions
The system is designed to be extensible through the MCPHandler interface. Developers can create specialized handlers to process specific message types or commands.
Built-in Handlers
The project includes several reference implementations for standard operations:
- EchoHandler: Simple utility that mirrors request content for testing.
- ContextVariableHandler: Manages the retrieval and storage of variables within the
MCPContext(e.g.,set_variableorget_variableactions). - TaskHandler: (Example) Used in integration scripts to simulate task execution results.
Sources: src/mcp/protocol.py:317-336, src/mcp/protocol.py:339-373, examples/mcp_integration.py:20-33
Event Hooks
The protocol supports five types of event hooks for cross-cutting concerns like logging or auditing:
before_sendafter_sendbefore_receiveafter_receiveon_error
Sources: src/mcp/protocol.py:133-140, examples/mcp_integration.py:53-58
Integration with Agent Systems
In the WIREDUP ecosystem, agents utilize MCP to communicate with other services or users. Agents can be wrapped in an AgentMCPHandler to bridge the gap between protocol messages and agent execution logic.
The sequence diagram demonstrates a typical interaction between a user request and an agent via the MCP layer.
Sources: AGENT.md:273-288, AGENT.md:291-310
Tool Calling and Interoperability
MCP explicitly supports tool calling, allowing an AI assistant to request external actions.
- create_tool_call: Formats a message with a specific tool name and parameters.
- create_tool_response: Encapsulates the result of a tool execution to be sent back to the requester.
Sources: src/mcp/protocol.py:209-228, src/mcp/protocol.py:231-249
Technical Summary
The MCP Protocol is a production-ready communication framework that combines strict typing with flexible extension points. By managing session history and context variables natively, it allows agents to maintain long-running conversations and complex multi-step tool interactions without manual state tracking in the business logic.
Sources: public/index.html:200-210, src/mcp/protocol.py:108-115