## Summary Developers are increasingly working in AI-native environments (e.g., Cursor, Claude, Copilot, terminal-based workflows) where planning, coding, debugging, and reasoning happen outside of GitLab’s UI. GitLab’s AI capabilities (Duo, agents, flows, and GitLab-native context) are currently optimized for use *within* GitLab. This creates a disconnect between where developers **work** and where GitLab’s **intelligence and automation** exist. This leads to: - Fragmented AI usage across tools - Reduced value of DAP investments outside GitLab GitLab is uniquely positioned to provide AI orchestration because it already owns the system of record for the SDLC—issues, code, pipelines, and security which allows agents and flows to operate with full lifecycle context and governance. However, external AI tools are rapidly becoming the primary interface for development, if GitLab does not extend DAP into these environments, those tools will become the de facto orchestration layer for AI workflows, and GitLab risks being reduced to a system of record rather than a system of execution. ### Proposal > [!NOTE] Value positioning > GitLab becomes the SDLC‑centric AI orchestration layer that follows developers across tools, not just a feature inside one UI. Make DAP agents and flows available to external developer tools through MCP, enabling developers to invoke GitLab’s AI capabilities directly from environments like Cursor, VS Code, and terminal-based workflows. Today, external tools can access GitLab data and perform basic actions, but they cannot access the agents and workflows that teams have built and rely on inside GitLab. This limits the value of DAP to GitLab’s UI and prevents customers from using their AI investments where development actually happens. By exposing DAP agents and flows through MCP we can offer orchestration, governance, and observability regardless of where those capabilities are used. Additionally, this expands DAP consumption beyond GitLab’s UI, increasing total usage by embedding GitLab-powered workflows into daily development interactions across external tools. --- --- <details> <summary>Market context</summary> #### Market context - Atlassian is already leaning into MCP with Jira/Confluence as first‑class MCP servers and is likely surface “Jira agents” the same way. - GitHub / Copilot ecosystem: GitHub MCP endpoints and “agent behind MCP” patterns are emerging; Microsoft is exposing [Foundry agents](https://learn.microsoft.com/en-us/agent-framework/agents/tools/hosted-mcp-tools?pivots=programming-language-csharp) and hosted MCP tools similarly. - Open ecosystems (LastMile, LangChain MCP, etc.): frameworks like [mcp-agent](https://github.com/lastmile-ai/mcp-agent) are specifically built to expose agents as MCP servers and have already normalized the “agent as MCP tool” pattern. </details> <details> <summary>Target buyers</summary> #### Target buyers * Platform / DevOps leaders, Heads of Eng, AppSec leads * Single AI governance and observability layer for SDLC agents, regardless of which AI frontend devs prefer * Ability to standardize on vetted agents/flows and expose them everywhere, not re‑implement them in each tool * Reduced shadow IT: they can authorize GitLab DAP once, and plug into many MCP‑capable hosts </details> <details> <summary>Target users</summary> #### Target users * Developers working primarily in IDEs (Cursor, VS Code, JetBrains, etc.) * Developers using AI assistants during coding workflows * Teams using external AI tools alongside GitLab * Platform teams standardizing AI usage across tools </details> <details> <summary>Workflow examples</summary> #### Workflow examples | Category | Examples | User intent | GitLab value | |----------|----------|------------|------------------------| | **Planning and ideation** | • Breaking down a feature into tasks<br>• Understanding requirements from a description<br>• Drafting work before creating issues | “Help me figure out what needs to be built and how to structure it” | • Project-aware planning<br>• Alignment with existing issues/epics<br>• Automatic creation of work items | | **In-development assistance** | • Reviewing code before opening an MR<br>• Generating tests<br>• Refactoring or improving code | “Help me improve this code before I share it” | • Awareness of team standards<br>• Alignment with past MRs<br>• Integration with project structure | | **Debugging and investigation** | • Understanding CI/CD failures<br>• Investigating test failures<br>• Diagnosing issues based on GitLab data | “Why did this fail and how do I fix it?” | • Access to pipeline logs and history<br>• Knowledge of CI configuration<br>• Pattern recognition across runs | | **Understanding existing work** | • Summarizing issues or MRs<br>• Understanding assigned tasks<br>• Reviewing historical decisions | “What do I need to do and why?” | • Rich context from issues, MRs, discussions<br>• Linking related work<br>• Reducing onboarding time | | **Taking action on GitLab from external tools** | • Creating or updating issues<br>• Commenting on MRs<br>• Triggering workflows | “Do this in GitLab without leaving my current tool” | • Maintaining GitLab as source of truth<br>• Reducing friction in updating work<br>• Enabling faster iteration loops | </details> <details> <summary>Governance and control plane</summary> #### Governance and control plane DAP usage via MCP would be governed through the existing control plane, no separate governance stack is introduced for external tools. </details> <details> <summary>Monetization</summary> #### Monetization Utilization of DAP agents and flows via MCP will incur GitLab credits usage under the same metering and billing model as when those agents and flows are invoked directly within the GitLab UI. </details> <details> <summary>Test Script</summary> Test scenario for invoking DAP foundational + custom agents from a third-party MCP client. Persona: a developer working in **Claude Code** who never leaves the IDE but reaches into GitLab's agents as callable MCP units. The beats chain into one SDLC storyline: **plan → research → human codes → review (three lenses) → diagnose CI**. The human writes the code; the agents wrap around the coding task. Support agentic mode 2 (hybrid - not fully agentic). > [!note] > > Customer context is **healthcare / HIPAA** so the custom agent is distinct from the security agent. #### Flow overview <table> <tr> <th> \# Click to sort ascending </th> <th> Agent Click to sort ascending </th> <th> Dev's situation (in Claude Code) Click to sort ascending </th> <th> What it stresses Click to sort ascending </th> </tr> <tr> <td>1</td> <td>Planner</td> <td>"Turn this feature idea into a plan"</td> <td> Long-running + **write** ops + HITL approval </td> </tr> <tr> <td>2</td> <td>Duo Dev (research)</td> <td>"Before I code, how do we do Okta SSO today?"</td> <td>Read across repo + Knowledge Graph; context flows back into the IDE</td> </tr> <tr> <td>—</td> <td> _Dev codes the change in Claude Code, opens !88_ </td> <td> _(human in the loop — the point of the demo)_ </td> <td>—</td> </tr> <tr> <td>3</td> <td>Duo Code Review</td> <td>"Review my MR !88"</td> <td>Reads human diff, returns structured findings; async</td> </tr> <tr> <td>4</td> <td>CI Expert</td> <td>"Pipeline on !88 is red — why?"</td> <td>Server-side job logs the local agent can't see</td> </tr> <tr> <td>5</td> <td>Security Agent</td> <td>"Any vulns in !88?"</td> <td>Cross-ref working tree + GitLab SAST / dep-scan</td> </tr> <tr> <td>6</td> <td>Custom: HIPAA/PHI Reviewer</td> <td>"Check !88 against our PHI controls"</td> <td>Customer-authored agent + discovery</td> </tr> </table> **Three reviews, one MR.** Beats 3, 5, 6 all review !88 — run them general → security → compliance and say the framing out loud so it reads as _layered governance_, not repetition: * Duo Code Review → code quality & correctness * Security Agent → vulnerabilities * HIPAA Reviewer → compliance controls --- ### Beat-by-beat test cases #### 1. Planner — write ops + HITL * **Prompt:** _"Use the GitLab Planner to break 'patient-portal SSO with Okta' into an epic with issues and a milestone."_ * **Illustrative call:** `invoke_agent(agent="planner", input="patient-portal SSO with Okta", project=<id>)` * **Expected:** proposed epic + child issues + milestone returned for approval, _then_ created in GitLab on confirm. <table> <tr> <th> Check Click to sort ascending </th> <th> Pass Click to sort ascending </th> </tr> <tr> <td>Plan returned as a proposal before anything is written</td> <td></td> </tr> <tr> <td>Writes gated behind explicit dev approval (not fire-and-forget)</td> <td></td> </tr> <tr> <td>Created epic/issues/milestone actually appear in GitLab</td> <td></td> </tr> </table> #### 2. Duo Dev (research mode) — context back to the IDE * **Prompt:** _"Before I write this, ask Duo to research how our codebase handles Okta/OIDC today and what SSO patterns already exist."_ * **Illustrative call:** `invoke_agent(agent="duo_developer", mode="research", input="existing Okta/OIDC + SSO patterns in this repo")` * **Expected:** synthesized findings — relevant files, existing auth utilities, prior art — returned as text the dev reads _before_ coding. <table> <tr> <th> Check Click to sort ascending </th> <th> Pass Click to sort ascending </th> </tr> <tr> <td>Findings reference real files / utilities in the repo</td> <td></td> </tr> <tr> <td>Output is usable context Claude Code can act on (not a dead-end blob)</td> <td></td> </tr> <tr> <td>Draws on Knowledge Graph / cross-repo context the local agent lacks</td> <td></td> </tr> </table> #### — Dev codes the change and opens MR !88 Human writes the feature in Claude Code using the plan (1) and research (2), pushes, opens **!88**. No agent call — this is the point of the demo. #### 3. Duo Code Review — reviewing a human-authored diff * **Prompt:** _"Run Duo Code Review on !88."_ * **Illustrative call:** `invoke_agent(agent="duo_code_review", mr=88)` * **Expected:** structured review comments on the human diff — quality, correctness, maintainability. <table> <tr> <th> Check Click to sort ascending </th> <th> Pass Click to sort ascending </th> </tr> <tr> <td>Comments are specific to the actual diff (not generic)</td> <td></td> </tr> <tr> <td>Long-running call returns cleanly (handle/poll or stream, not a timeout)</td> <td></td> </tr> <tr> <td>Findings distinguishable from security/compliance lenses below</td> <td></td> </tr> </table> #### 4. CI Expert — server-side context the local agent can't see * **Prompt:** _"The pipeline on !88 is failing. Ask the CI Expert what's wrong."_ * **Illustrative call:** `invoke_agent(agent="ci_expert", mr=88)` * **Expected:** reads job logs + `.gitlab-ci.yml` server-side, returns root cause + suggested fix. <table> <tr> <th> Check Click to sort ascending </th> <th> Pass Click to sort ascending </th> </tr> <tr> <td>Diagnosis cites actual failing job / log lines</td> <td></td> </tr> <tr> <td>Uses pipeline data the local IDE does not have</td> <td></td> </tr> <tr> <td>Suggested fix is actionable in the repo</td> <td></td> </tr> </table> #### 5. Security Agent — cross-reference diff + GitLab scan data * **Prompt:** _"Before I request review on !88, have the Security Analyst check it."_ * **Illustrative call:** `invoke_agent(agent="security_analyst", mr=88)` * **Expected:** correlates the diff with GitLab SAST / dependency-scanning findings, returns prioritized issues. <table> <tr> <th> Check Click to sort ascending </th> <th> Pass Click to sort ascending </th> </tr> <tr> <td>Pulls GitLab-side SAST / dep-scan results</td> <td>☐</td> </tr> <tr> <td>Prioritizes findings (not a flat dump)</td> <td>☐</td> </tr> <tr> <td>Clearly a security lens, distinct from Duo Code Review</td> <td>☐</td> </tr> </table> #### 6. Custom HIPAA/PHI Reviewer — custom agent + discovery * **Prompt:** _"Run our PHI Data-Handling Reviewer on !88."_ * **Illustrative call:** `invoke_agent(agent="highmark/phi-reviewer", mr=88)` * **Expected:** checks the change against customer-authored rules (no PHI in logs, encryption-at-rest for patient fields, audit-log coverage), returns pass/flag with citations to their control docs. <table> <tr> <th> Check Click to sort ascending </th> <th> Pass Click to sort ascending </th> </tr> <tr> <td>Applies customer-authored rules, not generic security checks</td> <td></td> </tr> <tr> <td>Cites the customer's own control docs</td> <td>☐</td> </tr> <tr> <td> Custom agent is **discoverable** via `list_agents` (not just by hardcoded name) </td> <td></td> </tr> </table> --- ### Hard-parts checklist Run these deliberately across the beats above to try to break it. <table> <tr> <th> Dimension Click to sort ascending </th> <th> How to test Click to sort ascending </th> <th> Pass Click to sort ascending </th> </tr> <tr> <td> **Long-running** </td> <td>Does Duo Code Review (3) return a handle + let you poll, or hang/timeout?</td> <td></td> </tr> <tr> <td> **HITL** </td> <td>Does Planner (1) gate writes behind approval, or fire-and-forget?</td> <td></td> </tr> <tr> <td> **Identity / permissions** </td> <td> Run a beat as a dev who **lacks** write access — confirm it's denied, and confirm _whose_ creds run the flow (dev PAT scope vs service identity). </td> <td></td> </tr> <tr> <td> **Trace continuity** </td> <td>Does the trace survive the MCP boundary, or go dark once it leaves Claude Code?</td> <td></td> </tr> <tr> <td> **Discovery** </td> <td> Can the client enumerate agents (`list_agents`), or must names be hardcoded? </td> <td></td> </tr> <tr> <td> **Error shape** </td> <td>Kill a pipeline mid-diagnosis (4) — clean MCP error or a wall of stack trace?</td> <td></td> </tr> </table> --- </details> # Implementation Proposal ## Goal Bring the hackathon prototype gitlab-org/gitlab!246597 (Expose DAP flows and agents through the MCP server) to production quality as a series of small, independently shippable MRs. ## Architectural decision The prototype's `Ai::DuoWorkflows::ExecuteAgentTurnService` opened the DWS `ExecuteWorkflow` gRPC stream directly from Rails and proxied `runHTTPRequest` actions with hand-rolled Workhorse-signed JWTs. **This is dropped.** No production path holds that stream in Rails today — it is always Workhorse (browser websocket, and the CI executor which reconnects through the same `/ws` endpoint) or the client itself (IDE via `direct_access`). Duplicating `workhorse/internal/ai_assist/duoworkflow` in Rails would ship without its safeguards (Redis session locking, graceful shutdown, token plumbing) and ties up Puma threads for up to 90s per turn. Instead, everything is **async: trigger → poll → approve → poll**. MCP callers are agents; polling fits, and matches how flows already execute (CI workloads via the production-hardened `Ai::Catalog::ExecuteWorkflowService` path — the same mechanism the Slack `@Duo` integration uses server-side, with composite identity, service accounts, quotas and governance handled). This collapses the prototype's sync tools (`ask_duo_agent`, `approve_duo_agent_action`) into the same trigger/approve/poll model as flows: fewer tools, one mental model. ## Tool set <table> <tr> <th> Tool Click to sort ascending </th> <th> Kind Click to sort ascending </th> <th> Purpose Click to sort ascending </th> </tr> <tr> <td> `trigger_duo_flow` </td> <td> route-backed (`route_setting :mcp`) </td> <td>Start a foundational or custom catalog flow (later: chat agents)</td> </tr> <tr> <td> `approve_duo_flow` </td> <td>route-backed</td> <td>Answer plan/tool-call approvals on a paused session</td> </tr> <tr> <td> `get_duo_session` </td> <td>GraphQL</td> <td>Poll a session: status, pause reason, last message</td> </tr> <tr> <td> `list_duo_agents` </td> <td>GraphQL</td> <td>Discover agents and flows available in a project</td> </tr> </table> (`list_duo_sessions` already shipped separately.) ## Iterations **Iteration 1 — Drive Duo flows from any MCP client** gitlab-org/gitlab#617171, gitlab-org/gitlab#617172, gitlab-org/gitlab#617173 ship together as one user-facing increment: discovery → trigger → poll → approve for flows, which already run in production as CI workloads. None of the three is useful alone (trigger without polling is fire-and-forget; polling without trigger is pointless; without discovery callers must hardcode references). Demoable end-to-end: trigger a `security_review/v1` from an external MCP client, approve its plan, get the result. **Iteration 2 — Talk to Duo agents from any MCP client** gitlab-org/gitlab#617174 is a separate increment: same three tools, but `trigger_duo_flow` widened to foundational chat agents. Split out because it carries the epic's only real unknown (spike: do chat-agent definitions run in the `ambient` CI environment, or is a messaging-adapter pivot needed?) and a different value/latency story (conversational turns vs. async jobs). Clients built against Iteration 1 get agents with no API change if the spike succeeds.