APEX Remote MCP Service Proposal

Requested By: Robert Matsuoka Initiative: I-2026-ITP-001 Technical Spec: duetto-code-intelligence/docs/APEX-MCP-SPEC.md

The Problem

APEX adoption is bottlenecked by workflow friction. Creating or updating an artifact today requires: cloning the repo, understanding frontmatter schemas, running local validation, committing, and opening a PR. This works for the 5–6 people who live in APEX, but it's too much for the broader R&D org.

The result: status fields go stale, proposals don't get written, and the product hierarchy is only as current as its most dedicated maintainer.

The Proposal

Extend duetto-code-intelligence (DCI) with an APEX-aware MCP service — available to every Claude Code, Cursor, and Claude Desktop user on the team. The service exposes:

1. An APEX Chat agent (Claude Sonnet 4.6) with deep APEX context, answering questions like "what's in delivery right now?" or "how do I create a PRD?" — and providing links back to canonical Docusaurus pages.

2. APEX MCP tools for read operations (list initiatives, get initiative, list open PRs) available immediately, and write operations (create initiative, create proposal, update status) gated behind a one-time GitHub OAuth connection in DCI Settings.

3. A dedicated /apex UI in DCI for direct browser-based APEX Chat interaction.

Architecture Summary

Claude Code / Cursor / Claude Desktop
    ↓  MCP JSON-RPC (HTTPS)
DCI  /mcp  ─────────────────────────────────────┐
    apex_chat           → Sonnet 4.6 + APEX prompt│
    apex_list_*         → APEX repo clone (read)  │
    apex_create_*       → GitHub as the user       │
    apex_update_status  → GitHub as the user       │
                                                   │
DCI /apex (web UI) ────────────────────────────────┘

Token security: GitHub OAuth tokens stored encrypted (Fernet AES-128-CBC) in DCI DB. Fernet key in AWS Secrets Manager.

What already exists in DCI: MCP endpoint, JWT auth, Google OAuth, AWS Bedrock/Claude, APEX repo sync, APEX reader service. Phase 1 is mostly wiring, not greenfield.

Implementation Plan

Phase 1 — Read + Chat (3–4 days)

• Extend ApexService for full frontmatter parsing
• Add ApexAgentService (Sonnet 4.6 + APEX system prompt)
• Add 4 MCP tools: apex_chat, apex_list_initiatives, apex_get_initiative, apex_list_prs
• APEX Chat UI at /apex

Phase 2 — GitHub OAuth + Writes (3–4 days)

• Register GitHub OAuth App in duettoresearch org
• Add GitHubAuthAdapter + OAuth routes
• Extend User model with encrypted github_access_token
• Add 3 write tools: apex_create_initiative, apex_create_proposal, apex_update_status
• "Connect GitHub" flow in DCI Settings

Phase 3 — Polish (1–2 days)

• Initiative dashboard, deep links, rate limiting, audit log

Total: 7–10 engineering days

Success Criteria

Kill signal: <10 users after 4 weeks of Phase 1 → pause Phase 2.

Scope Boundaries

This is NOT: - A JIRA replacement (JIRA is downstream; APEX is upstream) - A general GitHub integration (APEX repo only) - Real-time sync (nightly sync, same as today)

Open Questions

1. GitHub OAuth App registration: Who approves duettoresearch org app registrations? (Kartik or Bob?)
2. Draft PR or push-branch-only? create_initiative creates a branch — should the tool also auto-open a draft PR?
3. Sonnet 4.6 model: Available in DCI's Bedrock region? Or do we need to verify?
4. APEX sync frequency: Do write operations need to trigger a sync, or is daily fine for the MVP?

Approval

• [ ] Kartik — Product/architecture approval
• [ ] Bob — CTO approval + GitHub OAuth App registration

This document is DRAFT. See Initiative.md for full detail and the DCI spec for implementation specifics.