ADR-017: MCP Implementation Architecture for Hybrid-Cloud Integration¶

Note: This ADR consolidates 3 source documents during the 2026-01-28 namespace consolidation: - mcp-implementation-architecture-2026-01-12.md - mcp-implementation-executive-summary-2026-01-12.md - EXECUTIVE_SUMMARY.md

Status: Accepted Date: 2026-01-28 (consolidated from 2026-01-12 originals) Deciders: @cloud-architect, @product-owner, HITL/Manager Framework: ADLC v3.0.0 Constitutional Principle: II. Interoperability & Security, IV. Hybrid Deployment

Executive Summary¶

Architecture for implementing 33 MCP servers across 8 configurations enabling AI agents to access real-time cloud APIs for AWS (50+ accounts), Azure, Atlassian, and Microsoft 365.

Key Decisions: - ✅ Phased Rollout (AWS Phase 1 → Azure Phase 2 → Enterprise Tools Phase 3) - ✅ MCP Gateway Pattern (Cloudflare Workers + OPA policy enforcement) - ✅ Agent-MCP Allocation Matrix (least-privilege per agent type) - ✅ 3-Tier Validation Framework (≥99.5% accuracy target) - ✅ Migrate MCP Validation to CloudOps-Runbooks (PyPI distribution)

Technical Readiness: 78% (weighted average across 4 domains)

Context¶

Problem Statement¶

Cloud-Infrastructure requires standardized AI agent access to: 1. AWS Landing Zone: 50+ accounts (Organizations, Control Tower, SSO) 2. Azure CloudOps: Management Groups, Policy, Cost Management, Entra ID 3. Enterprise Tools: Atlassian (Jira/Confluence), Microsoft 365 (Teams/Graph)

Existing Infrastructure¶

Component	Count	Purpose
MCP Configurations	8 files	Domain-specific server groupings
MCP Servers	33 total	Real-time API access for agents
ADLC Agents	9 core	Constitutional governance
Validation Framework	3-tier	Progressive quality gates

Decision¶

Domain Readiness Matrix¶

Domain	Technical Readiness	Complexity	Risk	Recommendation	Timeline
AWS Landing Zone	92%	Medium	Low	IMPLEMENT	Phase 1 (Week 1-2)
Azure CloudOps	85%	Medium	Medium	IMPLEMENT	Phase 2 (Week 3-6)
Atlassian (Jira/Confluence)	65%	High	Medium	PILOT	Phase 3 (Week 7-12)
Microsoft 365/Teams	70%	High	Medium	PILOT	Phase 3 (Week 7-12)

MCP Configuration Files¶

Config	Servers	Rate Limit	Purpose
`.mcp-aws.json`	12	100/min	AWS Landing Zone operations
`.mcp-azure.json`	8	100/min	Azure CloudOps management
`.mcp-finops.json`	5	100/min	Cross-cloud FinOps (FOCUS 1.3)
`.mcp-terraform.json`	2	100/min	HashiCorp Registry, AWS Labs
`.mcp-testing.json`	2	200/min	Playwright, Markdown Lint
`.mcp-github.json`	1	60/min	PRs, Issues, Workflows
`.mcp-mkdocs.json`	1	200/min	Documentation Build/Serve
`.mcp-atlassian.json`	2	60/min	JIRA/Confluence (Pilot)

Architecture¶

MCP Gateway Pattern¶

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MCP Gateway Layer                                  │
│  ┌────────────────────────────────────────────────────────────────────┐    │
│  │  Cloudflare Workers (Edge Network)                                  │    │
│  │  ├── Rate Limiting      (Token bucket per agent, per MCP server)   │    │
│  │  ├── Policy Enforcement (OPA - Open Policy Agent)                  │    │
│  │  ├── Audit Logging      (S3 + CloudWatch Logs)                     │    │
│  │  └── Kill-Switch        (settings.local.json override)             │    │
│  └────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         │                           │                           │
   ┌─────▼──────┐             ┌─────▼──────┐             ┌─────▼──────┐
   │AWS MCPs(12)│             │Azure MCPs  │             │Enterprise  │
   │            │             │(8 servers) │             │MCPs (5+)   │
   │ - Orgs     │             │ - ARM      │             │ - Atlassian│
   │ - SSO      │             │ - Policy   │             │ - M365     │
   │ - Cost     │             │ - Cost     │             │ - Graph    │
   │ - Security │             │ - Security │             │            │
   └────────────┘             └────────────┘             └────────────┘

Agent-MCP Allocation Matrix¶

Agent	Read-Only MCPs	Write MCPs (HITL)	Phase
product-owner	AWS Resource Explorer, Azure Policy, Jira queries	None	Phase 1, 3-A
cloud-architect	AWS Organizations, Azure Entra, Graph Calendar	Control Tower, Entra PIM, Jira write	Phase 1-3
security-compliance-engineer	Security Hub, Security Center, Config	None	Phase 1-2
observability-engineer	Cost Explorer, Cost Management, FOCUS aggregator	Teams notifications	Phase 2

Security Model¶

Domain	Authentication	Authorization	Audit
AWS	SSO (SAML 2.0) + IAM Roles	Least-privilege per MCP	CloudTrail
Azure	Service Principal (certificate)	RBAC + Conditional Access	Azure Monitor
Atlassian	OAuth 2.1 (PKCE)	Scopes (read vs write)	Cloudflare Edge
Microsoft 365	OAuth 2.1 (Azure AD)	Graph API permissions	Azure AD Audit

Domain 1: AWS Landing Zone MCPs (92% - IMPLEMENT)¶

Configuration¶

# .mcp-aws.json (PRODUCTION)
mcpServers:
  # Phase 1: Read-Only (Low Risk)
  awslabs-resource-explorer:
    transport: stdio (uvx)
    auth: AWS_MANAGEMENT_PROFILE (IAM role: ViewOnlyAccess)
    rate_limit: 100 req/min
    agents: [cloud-architect, security-compliance-engineer]
    checkpoints: [CHK007, CHK008, CHK011]

  awslabs-security-hub:
    transport: stdio (uvx)
    auth: AWS_OPERATIONS_PROFILE (IAM role: SecurityAuditor)
    rate_limit: 100 req/min
    agents: [security-compliance-engineer]
    checkpoints: [CHK019, CHK020, CHK021]

  # Phase 2: FinOps (Medium Risk, High Value)
  awslabs-cost-explorer:
    transport: stdio (uvx)
    auth: AWS_BILLING_PROFILE (IAM role: Billing)
    rate_limit: 50 req/min
    agents: [observability-engineer]
    validation: cross-validate (≥99.5%)
    checkpoints: [CHK048, CHK049]

  # Phase 3: Orchestration (High Risk, HITL Required)
  awslabs-organizations:
    transport: stdio (uvx)
    auth: AWS_MANAGEMENT_PROFILE
    rate_limit: 20 req/min
    agents: [cloud-architect]
    hitl_approval: true
    checkpoints: [CHK007, CHK014, CHK015]

AWS MCPs (12 servers)¶

Server	Profile	IAM Role	Rate Limit	Risk
awslabs-organizations	MANAGEMENT	OrganizationAccountAccessRole	20/min	HIGH (HITL)
awslabs-identity-center	MANAGEMENT	AWSSSOMasterAccountAdministrator	50/min	HIGH (HITL)
awslabs-control-tower	MANAGEMENT	AWSControlTowerAdmin	10/min	HIGH (HITL)
awslabs-cost-explorer	BILLING	Billing	50/min	MEDIUM
awslabs-security-hub	OPERATIONS	SecurityAuditor	100/min	LOW
awslabs-config	OPERATIONS	ConfigRulesReader	100/min	LOW
awslabs-iam	DEFAULT	ViewOnlyAccess	100/min	LOW
awslabs-vpc	OPERATIONS	NetworkViewer	100/min	LOW
awslabs-cloudformation	DEFAULT	CloudFormationReader	100/min	LOW
awslabs-resource-explorer	MANAGEMENT	ViewOnlyAccess	100/min	LOW
awslabs-service-catalog	OPERATIONS	ServiceCatalogViewer	100/min	LOW
awslabs-core	DEFAULT	ReadOnlyAccess	100/min	LOW

Domain 2: Azure CloudOps MCPs (85% - IMPLEMENT)¶

Configuration¶

# .mcp-azure.json (PRODUCTION)
mcpServers:
  # Phase 1: Read-Only Governance
  azure-policy:
    transport: stdio (uvx azure-mcp-server@latest --service policy)
    auth: Service Principal (RBAC: Reader)
    rate_limit: 100 req/min
    agents: [security-compliance-engineer, cloud-architect]
    checkpoints: [CHK007, CHK019, CHK020]

  azure-security-center:
    transport: stdio (uvx azure-mcp-server@latest --service security-center)
    auth: Service Principal (RBAC: Security Reader)
    rate_limit: 100 req/min
    agents: [security-compliance-engineer]
    checkpoints: [CHK019, CHK021]

  # Phase 2: FinOps (FOCUS 1.3)
  azure-cost-management:
    transport: stdio (uvx azure-mcp-server@latest --service cost-management)
    auth: Service Principal (RBAC: Cost Management Reader)
    rate_limit: 50 req/min
    agents: [observability-engineer]
    focus_version: "1.3"
    cross_validation: AWS Cost Explorer (≥99.5%)
    checkpoints: [CHK048, CHK049]

  # Phase 3: Identity (HITL Required)
  azure-entra:
    transport: stdio (uvx azure-mcp-server@latest --service entra)
    auth: Service Principal (RBAC: Privileged Role Administrator - read-only)
    rate_limit: 20 req/min
    agents: [cloud-architect]
    hitl_approval: true
    checkpoints: [CHK011, CHK012, CHK013]

Azure MCPs (8 servers)¶

Server	Service	RBAC Role	Rate Limit	Risk
azure-resource-manager	ARM	Reader	100/min	LOW
azure-policy	Policy	Reader	100/min	LOW
azure-cost-management	Cost	Cost Management Reader	50/min	MEDIUM
azure-cost-management-focus	Cost	Cost Management Reader	50/min	MEDIUM
azure-security-center	Defender	Security Reader	100/min	LOW
azure-entra	Entra ID	Directory Reader	20/min	HIGH (HITL)
azure-cost-anomaly-detection	Cost	Cost Management Reader	50/min	MEDIUM
azure-advisor	Advisor	Reader	100/min	LOW

Domain 3 & 4: Enterprise Tools (65-70% - PILOT)¶

Atlassian (Jira/Confluence)¶

Status: PILOT (Week 7-12) Blocker: SSE transport deprecated (May 2025) → migrate to Streamable HTTP

Server	Transport	OAuth Scopes	Risk
atlassian-rovo-jira	SSE → HTTP	read:jira-work	MEDIUM
atlassian-rovo-confluence	SSE → HTTP	read:confluence-content.all	MEDIUM

Microsoft 365/Teams¶

Status: PILOT (Week 7-12) Dependency: Graph API MCP adapter (REST → MCP bridge)

Server	Transport	Graph Permissions	Risk
microsoft-teams-notifications	HTTPS	ChannelMessage.Send	LOW
microsoft-sharepoint-upload	HTTPS	Sites.ReadWrite.All	MEDIUM (HITL)
microsoft-graph-calendar	HTTPS	Calendars.ReadWrite	HIGH (HITL)

MCP Validation Migration¶

Decision: Migrate to CloudOps-Runbooks¶

Confidence: 92% Effort: 3 hours Value: HIGH (enables PyPI distribution)

Migration Scope¶

CloudOps-Runbooks/src/runbooks/mcp/
├── integration.py          # Existing EnterpriseMCPIntegrator
└── validation/             # NEW - migrated code (1,175 LOC)
    ├── core/               # Core validation logic
    ├── validators/         # Domain-specific validators
    ├── comparators/        # Response comparison
    ├── evidence/           # Evidence generation
    └── cli.py              # mcp-validate CLI (Typer)

Import Path Changes¶

# Before (Cloud-Infrastructure)
from mcp_validation.validators import AWSOrganizationsValidator

# After (CloudOps-Runbooks)
from runbooks.mcp import AWSOrganizationsValidator  # Recommended

Migration Timeline¶

Phase	Date	Deliverable
Migration	2026-01-12	Code moved, tests passing
PyPI Publish	2026-01-19	runbooks v1.2.0 with MCP validation
Deprecation End	2026-06-01	Remove wrapper from Cloud-Infrastructure

3-Tier Validation Framework¶

Tier	Environment	Duration	Cost	Coverage	Threshold
Tier 1	Functional (Snapshot)	2-3s	$0	70-80%	MCP protocol conformance
Tier 2	Integration (Real APIs)	5-10m	~$25/mo	+15-20%	≥99.5% accuracy
Tier 3	E2E (Agent Workflows)	15-30m	~$100/mo	+5-10%	≥95% checkpoints

Validation Command¶

# Run full PDCA validation cycle
uv run mcp-validate pdca aws --max-cycles 7

# Cross-validate specific domain
uv run mcp-validate aws --verbose
uv run mcp-validate azure --focus-version 1.3

Phased Rollout Timeline¶

Phase	Duration	Domains	Go/No-Go Gate
Phase 1	Week 1-2	AWS Landing Zone (12 MCPs)	MCP Gateway operational, Tier 2 ≥99.5%
Phase 2	Week 3-6	Azure CloudOps (8 MCPs), FinOps (5 MCPs)	FOCUS 1.3 cross-validation ≥99.5%
Phase 3-A	Week 7-8	Atlassian read-only (2 MCPs)	OAuth 2.1 functional
Phase 3-B	Week 9-10	Microsoft 365 notifications (1 MCP)	Graph API adapter deployed
Phase 3-C	Week 11-12	Enterprise write operations (4 MCPs)	HITL approval workflow operational

Rollback Procedures¶

RTO Target: ≤30min RPO Target: ≤5min

Domain	Trigger	Action	RTO
AWS	Tier 2 <95%, IAM failures	Kill-switch (settings.local.json)	5min
Azure	Service Principal auth failures	Revert to Azure CLI	15min
Atlassian	SSE failures, OAuth issues	Disable Rovo MCPs	10min
Microsoft 365	Graph throttling, consent revoked	Disable Graph MCPs	20min

Consequences¶

Positive¶

Unified API Access: 33 MCP servers provide consistent AI agent interface
Cross-Cloud FinOps: FOCUS 1.3 normalization enables hybrid cost analysis
Security Enforcement: MCP Gateway + OPA policies enforce least-privilege
Validation Parity: ≥99.5% accuracy matches CloudOps-Runbooks pattern
PyPI Distribution: Single pip install runbooks includes MCP validation

Negative¶

Gateway Complexity: Single point of failure (mitigated by multi-region)
OAuth Overhead: Atlassian/M365 require complex OAuth 2.1 flows
Migration Effort: 6-month deprecation period for import path changes

Risks¶

Risk	Probability	Impact	Mitigation
SSE Deprecation (Atlassian)	HIGH	HIGH	Migrate to Streamable HTTP (Phase 3 gate)
Graph API Throttling	MEDIUM	HIGH	Adaptive rate limiting, retry-after
Service Principal Expiration	MEDIUM	HIGH	Certificate-based auth (2-year), auto-renewal
MCP Gateway SPOF	LOW	HIGH	Multi-region Cloudflare Workers

ADLC Checkpoint Coverage¶

Principle	Checkpoints	Coverage	Status
II. Interoperability & Security	CHK007-CHK013	88%	PASS (AWS/Azure), PILOT (Enterprise)
III. Evaluation-First	CHK014-CHK021	92%	PASS (3-tier validation, HITL gates)
IV. Hybrid Deployment	CHK022-CHK028	85%	PASS (multi-cloud architecture)
V. Observability	CHK048-CHK054	80%	NEEDS WORK (SLO definition)
VI. Governance	CHK055-CHK058	90%	PASS (agent-MCP allocation)

Quality Gates¶

Gate	Target	Measurement	Rejection Criteria
MCP Gateway	Deployed	Cloudflare health check	Gateway unavailable → BLOCK Phase 1
Tier 2 Accuracy	≥99.5%	Cross-validation	<99.5% → REJECT domain deployment
FOCUS Coverage	37/37 columns	Schema validation	Missing columns → REJECT FinOps
HITL Workflow	Operational	Approval queue functional	Queue failure → BLOCK write ops
Checkpoint Pass	≥95%	Constitutional compliance	<95% → REJECT phase progression

Source Documents (Consolidated)¶

Original Document	Date	Key Contribution
`mcp-implementation-architecture-2026-01-12.md`	2026-01-12	Domain readiness matrix, 5W1H analysis, phased rollout
`mcp-implementation-executive-summary-2026-01-12.md`	2026-01-12	Quick decision matrix, risk register, checkpoint coverage
`EXECUTIVE_SUMMARY.md`	2026-01-12	MCP validation migration proposal, import path changes

Version: 1.0.0 ADLC Framework: v3.0.0 Maintainer: @cloud-architect Agreement Score: 78% (weighted average) Coordination Log: tmp/cloud-infrastructure/coordination-logs/cloud-architect-2026-01-28-adr-migration.json