Model Context Protocol (MCP) Bridge

Relevant source files

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

• services/api/integration/mcp_bridge.py
• services/api/agents/brain_agents/ai-engineer.md
• services/api/agents/brain_agents/search-specialist.md
• services/api/agents/brain_agents/task-decomposition-expert.md
• services/api/agents/brain_agents/research-coordinator.md
• services/api/agents/brain_agents/metadata-agent.md

The Model Context Protocol (MCP) Bridge provides a unified Python interface to all external MCP servers, including GitHub, Vercel, Supabase, and Slack. It serves as the primary communication layer for autonomous agents to interact with third-party platforms and internal infrastructure like the NeXifyAI Brain.

Sources: services/api/integration/mcp_bridge.py:1-9, services/api/agents/brain_agents/ai-engineer.md:58-64

Architecture Overview

The MCP Bridge acts as a routing layer within the NeXify Cognitive Execution Layer (NCEL) architecture. All external calls originating from agents flow through this bridge, which wraps native Hermes MCP tool invocations in typed Python methods.

Core Components

• MCPBridge: The central singleton that manages connections to specialized service clients.
• Service Clients: Specialized classes (e.g., GitHubMCP, SupabaseMCP) that define high-level methods for specific platforms.
• MCPToolResult: A standardized data structure that encapsulates tool execution results, status, latency, and error logs.
• MCPStatus: An enumeration tracking connection states such as CONNECTED, DISCONNECTED, ERROR, and RATE_LIMITED.

Sources: services/api/integration/mcp_bridge.py:17-48, services/api/agents/brain_agents/ai-engineer.md:65-72

System Relationships

The diagram below illustrates how the MCPBridge organizes service-specific clients to provide a single entry point for agents.

The MCPBridge class instantiates specialized clients to handle domain-specific logic while sharing a common invocation path.
Sources: services/api/integration/mcp_bridge.py:38-50

Execution Flow

When an agent initiates a tool call, the bridge routes the request through the Hermes Agent runtime. This runtime intercepts calls prefixed with mcp_* and directs them to the appropriate MCP server.

The sequence demonstrates the synchronous dispatch of tool requests from an agent to the external provider via the Hermes runtime.
Sources: services/api/integration/mcp_bridge.py:61-75, services/api/agents/brain_agents/task-decomposition-expert.md:88-97

NCEL Integration

Within the NeXify Cognitive Execution Layer (NCEL), MCP Routing is defined as Layer 5. Every outbound call includes a correlation ID to enable end-to-end tracing across the system.

Standard MCP Endpoints

Endpoint	Target Service	Usage
qdrant.search	NeXifyAI Brain	Semantic search for knowledge retrieval.
context-manager.get_context	Session State	Fetches session state and ensures tenant isolation.
brain.write	Memory Persistence	Writes findings back to the Brain after actions.
mcp_github_*	GitHub	Repository, Issue, and PR management.
supabase.*	Supabase	Database queries and schema migrations.

Sources: services/api/agents/brain_agents/ai-engineer.md:65-72, services/api/agents/brain_agents/search-specialist.md:73-81, services/api/agents/brain_agents/metadata-agent.md:92-100

Service Capabilities

GitHub Integration

The GitHubMCP client manages interactions with repositories, primarily for the nexifyai organization. It supports listing and creating issues, managing pull requests, and searching code or repositories.
Sources: services/api/integration/mcp_bridge.py:91-105

Vercel Integration

The VercelMCP client automates deployment workflows. It provides methods to trigger deployments, check status, and manage environment variables across production and preview environments.
Sources: services/api/integration/mcp_bridge.py:206-220

Supabase Integration

The SupabaseMCP client handles database operations. While read-only queries are the default, it supports insertions, updates, and schema migrations. It also allows calling stored procedures via RPC.
Sources: services/api/integration/mcp_bridge.py:270-285

Slack Integration

The SlackMCP client facilitates communication. It includes a notify helper that sends formatted messages with success, info, warning, or error levels using specific emojis.
Sources: services/api/integration/mcp_bridge.py:347-360

Health and Monitoring

The MCPHealthCheck class evaluates the connectivity of all MCP servers. It generates a health score representing the percentage of connected services.

# services/api/integration/mcp_bridge.py:408-422
def health_score(self) -> Dict[str, Any]:
    """Calculate MCP health score."""
    statuses = self.check_all()
    connected = sum(1 for s in statuses.values() if s == MCPStatus.CONNECTED)
    total = len(statuses)
    score = (connected / total * 100) if total > 0 else 0
    return {
        "mcp_health_score": score,
        "connected": connected,
        "total": total,
        "statuses": {k: v.value for k, v in statuses.items()},
    }

Sources: services/api/integration/mcp_bridge.py:408-422

The MCP Bridge ensures that all agent actions are logged and traceable, fulfilling the "No Mutation Without Re-Observation" mandate by providing the necessary tools for agents to verify system states before and after changes.
Sources: services/api/agents/brain_agents/ai-engineer.md:37-39