Overview
The GitLab MCP Orchestrator is an L3 strategic authority operating within the Strategic domain of the Prismatic Platform. This agent represents the next generation of GitLab orchestration, implementing a 3NL (3 Nested Levels) architecture with MCP (Model Context Protocol) Blackboard coordination. It was designed to replace the earlier GitLabEnforcer pattern with a secure, bounded, and fully observable orchestration model that provides transparent reasoning about GitLab operations through structured intelligence layers.
The 3NL architecture provides three nested levels of processing for GitLab operations: a Neural level that handles pattern recognition and anomaly detection across GitLab activity streams, a Logical level that applies rule-based governance and policy enforcement to proposed GitLab operations, and a Linguistic level that translates between human-readable strategic directives and machine-executable GitLab API operations. This layered approach ensures that every GitLab operation undergoes multi-level validation before execution, with each level providing independent verification from its own epistemic perspective.
3NL Architecture Integration
The MCP Orchestrator implements the three nested levels of the 3NL framework as distinct processing stages for GitLab operations.
L1 Neural Level. Pattern recognition across GitLab activity data identifies anomalies, trends, and correlations that inform strategic decisions. The Neural level processes commit frequency patterns, merge request review velocity, pipeline success rates, and issue resolution trends to generate situational awareness about development activity. Anomaly detection identifies unusual patterns such as sudden spikes in pipeline failures, unexpected branch creation activity, or abnormal merge request approval patterns that may indicate process issues or security concerns.
L2 Logical Level. Rule-based governance applies platform policies to proposed GitLab operations. Before any operation executes, the Logical level validates it against the policy framework, checking constraints such as branch protection rules, merge request approval requirements, label taxonomy compliance, and milestone assignment validity. Operations that violate policy constraints are rejected with detailed explanations of which rules were triggered and what corrective actions are required.
L3 Linguistic Level. Natural language processing translates strategic directives into executable GitLab operation sequences. When a strategic coordinator issues a high-level directive such as "prioritize security hardening for the next sprint," the Linguistic level decomposes this into concrete GitLab operations: creating issues with appropriate labels, adjusting milestone assignments, updating issue weights and priorities, and configuring pipeline stages to include additional security scanning.
MCP Blackboard Coordination
The Blackboard pattern provides a shared knowledge space where multiple agents can contribute information and coordinate actions without direct coupling. The MCP Orchestrator serves as the Blackboard coordinator for all GitLab-related operations, maintaining a shared state representation that is accessible to all participating agents.
Knowledge Sources. Each participating agent contributes specialized knowledge to the Blackboard. The gitlab-api-specialist-agent contributes API state information, the gitlab-strategic-coordinator contributes strategic priorities, and the gitlab-security-specialist-agent contributes security posture assessments. The Orchestrator aggregates these contributions into a unified operational picture.
Control Flow. The Blackboard implements an opportunistic control strategy where agents post observations and proposed actions to the shared space, and the Orchestrator evaluates which proposed actions should execute based on the current state of all knowledge sources. This approach enables complex multi-agent coordination without requiring explicit choreography between agents.
Conflict Arbitration. When multiple agents propose conflicting actions (such as different priority assignments for the same issue), the Blackboard's conflict resolution mechanism applies precedence rules based on agent authority level, temporal ordering, and policy compliance to determine the winning action.
Core Capabilities
The MCP Orchestrator provides six primary capabilities that leverage its 3NL architecture and Blackboard coordination model.
Secure Operation Execution. Every GitLab operation executes within a security boundary that validates authentication, authorization, and policy compliance before API calls are issued. The security boundary implements the principle of least privilege, ensuring that each operation uses only the minimum API permissions required for its specific task.
Observable Operation Tracing. Complete observability into operation execution through structured logging, telemetry events, and audit trail generation. Every operation produces a trace that includes the originating directive, 3NL processing decisions at each level, Blackboard state at the time of execution, and the resulting GitLab API interactions.
Bounded Execution Context. Operations execute within defined resource bounds including time limits, API call budgets, and state change scope. Runaway operations that exceed their bounds are automatically terminated and rolled back. This bounded execution prevents cascading failures and ensures that individual operation failures do not impact overall orchestration health.
Strategic Directive Translation. Transforming high-level strategic directives into sequences of concrete GitLab operations through the Linguistic level's decomposition capabilities. Complex directives that span multiple GitLab resource types are broken into atomic operations with dependency ordering and rollback points.
Cross-Domain Intelligence Synthesis. Aggregating intelligence from multiple domain-specific agents through the Blackboard to produce comprehensive operational assessments that no single agent could generate independently.
Adaptive Policy Enforcement. Dynamically adjusting enforcement strictness based on context. During normal operations, full policy enforcement applies. During declared emergencies, specific policy relaxations can be authorized through proper escalation channels with full audit logging.
Technical Implementation
The MCP Orchestrator is implemented as a supervised OTP application with a GenServer-based Blackboard process that maintains shared state in ETS tables. The Blackboard supports concurrent read access from multiple agent processes with serialized write access through the GenServer's message handling.
The 3NL processing pipeline is implemented as a GenStage chain where each level represents a processing stage. Operations flow from Linguistic (directive parsing) through Logical (policy validation) to Neural (pattern context enrichment), with the ability to short-circuit at any level if validation fails.
MCP protocol integration enables external tool connectivity through standardized JSON-RPC messaging. The Orchestrator exposes GitLab operations as MCP tools that can be invoked by Claude sessions and other MCP-compatible clients, providing a structured interface for AI-assisted development workflows.
Persistent state management uses Ecto schemas with PostgreSQL backing for the operation audit log and Blackboard state snapshots. Snapshots are taken at configurable intervals and retained for post-hoc analysis and compliance auditing.
Coordination Model
| Agent | Relationship | Domain |
|---|---|---|
| gitlab-strategic-coordinator | Receives strategic directives and provides execution status | Strategic |
| gitlab-full-circle-coordinator | Coordinates lifecycle management through Blackboard integration | Lifecycle |
| gitlab-api-specialist-agent | Provides underlying API execution capabilities | Integration |
| autonomous-pattern-evolution-specialist | Contributes pattern analysis to Blackboard knowledge sources | Evolution |
| Planner Agent | Receives planning directives translated through Linguistic level | Planning |
Security Model
The Orchestrator implements defense-in-depth security for all GitLab operations. API credentials are stored in encrypted Ecto fields and accessed only through the secure execution boundary. All operations are subject to RBAC validation before execution. The audit trail records every operation with sufficient detail to reconstruct the complete decision chain from directive to execution.
The MCP tool interface implements request validation that prevents injection attacks through tool parameters. Tool invocations are rate-limited per client to prevent abuse, and all tool responses are sanitized to prevent credential leakage.
Enforcement
The GitLab MCP Orchestrator operates under the NO MERCY, NO DOUBTS doctrine. Every GitLab operation must pass all three 3NL validation levels before execution. Blackboard contributions must include provenance information identifying the contributing agent and the evidence supporting the contribution. Operations that bypass the security boundary are logged as L3 violations and trigger immediate investigation. The Trinity Gate framework validates that strategic decisions derived from Blackboard intelligence pass structural, logical, and formal consistency checks before influencing GitLab operations.
Connect & Contribute
Created by Tomáš Korcak (korczis) | Open Source under GHL