## 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 | Tool | Kind | Purpose | | --- | --- | --- | | `trigger_duo_flow` | route-backed (`route_setting :mcp`) | Start a foundational or custom catalog flow (later: chat agents) | | `approve_duo_flow` | route-backed | Answer plan/tool-call approvals on a paused session | | `get_duo_session` | GraphQL | Poll a session: status, pause reason, last message | | `list_duo_agents` | GraphQL | Discover agents and flows available in a project | (`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. ## Scope notes - No feature flag: the MCP server has instance- and group-level enablement gates, and the underlying REST endpoints are `lifecycle: :experiment` - Push-style delivery (MCP SSE) out of scope; polling covers the caller-is-an-agent use case - Tool naming follows the documented `verb_object` conventions; alignment with the MCP tool proposal process is being clarified with Product separately