Add MCP server via AgentCore Gateway for analytics consumption (Quick Desktop + Kiro)

### Summary

Expose KCA analytics as MCP tools via **Amazon Bedrock AgentCore Gateway**, enabling two primary consumers:
1. **Managers via Amazon Quick Desktop** — natural-language exploration of team cost/usage analytics (aggregates + per-dev drill-down).
2. **Developers via Kiro** — personalized usage recommendations (self-scoped), with proactive suggestion of steerings/agents tailored to individual usage patterns.

### Motivation

KCA computes rich analytics (usage, cost, tier optimization, engagement, Git-Kiro correlation across GitHub and GitLab), but today only the bundled React SPA and direct REST calls consume them. With Amazon Quick Desktop supporting MCP natively and Kiro acting as MCP client, a single MCP server would:

- Give managers a **natural-language interface** to explore team cost/usage without navigating the SPA.
- Give developers **proactive, personalized optimization suggestions** in their IDE (Kiro), enabling generation of steerings and agents adapted to their usage patterns.
- Consolidate both use cases behind **one protocol, one endpoint, one auth story** — no bespoke per-consumer integrations.

### Architecture decisions

#### Host: AgentCore Gateway

KCA **already uses AgentCore** for the Git-Kiro correlation agent (`agent/app/GitCorrelationAgent/`, `backend/handlers/correlation_worker.py`). The AgentCore Gateway:
- Converts existing **Lambda handlers into MCP tools** with minimal code — no custom MCP protocol implementation needed.
- Provides managed **inbound OAuth (JWT authorizer)**, **observability**, **audit trail**, and **serverless scaling** out of the box.
- Supports **fine-grained access control** natively.
- Eliminates the need for a separate MCP framework.

#### Identity & authorization

| Concept | Implementation |
|---|---|
| **Authentication** | OAuth 2.0 authorization code + PKCE via **Cognito** (federating one or more Identity Center instances). Cognito already serves the SPA auth — reuse the same User Pool with a new app client for MCP. |
| **User mapping** | `(issuer + subject)` from JWT → `userId` in KCA's AnalyticsTable. If no match → deny. This handles multi-IdC orgs (dev logs into Kiro with one IdC, manager with another) cleanly. |
| **Role** | Custom attribute/tag in Identity Center: marks a user as manager. Propagated as a **claim in the JWT**. |
| **Scope boundary** | Identity Center **groups = teams**. Manager sees only devs in shared groups. Dev sees only self. |
| **userId derivation** | Always from token (server-side). Dev tools **never** accept `userId` as parameter. Manager tools accept it, validated against group membership. |

**Critical integration requirement:** Ensure the manager tag and group memberships propagate as **claims in the JWT** through the full Identity Center → Cognito federation → token chain. Test this early.

#### Recommendations & analytics model

| Access pattern | Strategy |
|---|---|
| **Team aggregate** (manager's first look) | Read from ETL-computed aggregates already in DDB (`GLOBAL` / `STATS#DAILY` / tier/client breakdowns via `account_usage_handler`). **Zero Bedrock cost.** |
| **Individual drill-down** (manager or self) | **On-demand + cache with freshness invalidation.** Reuses the existing `recommendation_handler` / `engagement_handler` logic. Cache invalidates when newer than last ETL run. |
| **Correlation analysis** | **Reuses the existing async pattern**: `ANALYSIS_PENDING` flag → async worker → persist with TTL → clear flag (see `correlation_worker.py`). Tool returns "pending" status; client retries. **Respects Quick's 60s timeout without blocking.** |
| **Pre-compute** | None. Access is sparse (manager picks specific devs in specific periods). Pre-computing for all users would be cost-prohibitive in orgs with hundreds of devs. |

**Fan-out guard:** No "analyze all devs" tool. Aggregate = cheap ETL data already in DDB. Individual drill-down = 1-at-a-time, on-demand.

#### Kiro proactive flow (developer self-service)

1. Session start → Kiro calls `get_my_profile()`.
2. If cache is fresh → suggests immediately ("I have optimization suggestions based on your usage — want me to create a steering?").
3. If cold → triggers async generation (same pending pattern); surfaces suggestion when ready (non-blocking).
4. Dev approves → Kiro creates steering/agent. **Never auto-applies silently.**

### Proposed MCP tools (draft)

Tools are **semantic and coarse-grained** (optimized for LLM tool-use, not CRUD):

| Tool | Maps to existing handler(s) | Auth scope |
|---|---|---|
| `get_team_summary` | `account_usage_handler` (GLOBAL stats) | manager |
| `get_user_detail` | `usage_handler` + `user_details_handler` | manager (group-validated) or self |
| `get_tier_recommendations` | `recommendation_handler` / `recommendation_engine` | manager or self |
| `get_engagement_metrics` | `engagement_handler` / `segmentation_engine` / `funnel_calculator` | manager |
| `get_my_profile` | New — structured profile for steering generation (preferred models, task categories, activity patterns) | self only |
| `get_correlation_summary` | `agent_correlation_handler` / `correlation_worker` (existing async pattern) | manager (group-validated) or self |

**Hard rules:**
- **Never expose raw prompt/response content** (`PROMPT#` items contain potentially proprietary code, secrets, PII). Only expose aggregated metrics, categories, and correlation insights.
- **Read-only surface only** — no mutation tools. Config changes (pricing, thresholds, git repos) stay in the SPA.
- **JSON Schema Draft 7+** for all tool `inputSchema` (Quick rejects Draft 3 `"required": true` syntax).
- **Max 100 tools** per Gateway connection (Quick limitation). Design for stability, not granularity.
- **Tombstoned users are excluded** — reuse the existing `_is_tombstoned()` check from `recommendation_handler`.

### Security controls

- **Data isolation:** `userId` derived server-side from token; group membership validated on every manager request.
- **Identity mapping defense:** `(issuer + subject)` key (never email-only) to prevent cross-IdC identity collision.
- **Encryption:** DDB and S3 at rest via KMS (already configured in template.yaml).
- **Rate limiting/throttling:** Configured at the Gateway level to prevent bulk exfiltration.
- **Audit:** Every tool invocation logged (who, which tool, parameters, timestamp) via AgentCore's built-in observability.
- **Connectivity:** Quick connects via **VPC connection** (private); only OAuth endpoints (Cognito Hosted UI) are public. Configure Route 53 Resolver inbound endpoints for DNS resolution.
- **60s timeout compliance:** No tool blocks longer than 60s. Expensive operations (correlation) return immediately with "pending" status and use the existing async worker pattern.

### Implementation leverage (existing patterns to reuse)

| Existing pattern | Reuse for MCP |
|---|---|
| `correlation_worker.py` async flow (PENDING flag → worker → persist → clear) | All cold-miss MCP tools that trigger Bedrock |
| `recommendation_engine.py` (pure, no I/O) | Direct call from MCP tool Lambda — zero duplication |
| `segmentation_engine.py` + `funnel_calculator.py` (pure) | Same — direct import from MCP tool |
| `analytics_repository.py` read methods | All tools that need DDB access |
| `agentcore.json` + `correlation_worker._invoke_agent()` | Pattern for wiring MCP tool Lambdas into AgentCore Gateway |
| User tombstoning filter | All tools exclude tombstoned users |

### Risks & work items (ordered by priority)

1. **Spike: Quick ↔ AgentCore Gateway interop** — Validate OAuth discovery (RFC 9728 Protected Resource Metadata, PKCE S256, RFC 8707 Resource Indicators) works end-to-end between Quick Desktop and an AgentCore Gateway with a trivial tool. Biggest unknown; cheapest to test first.
2. **Role + team boundary model** — Introduce manager tag in Identity Center + group-based scoping. New authorization layer in the MCP tools (not in the existing SPA backend — that remains admin-only).
3. **Claim propagation** — Confirm tag + groups arrive as claims in the JWT through the full Identity Center → Cognito federation chain.
4. **`get_my_profile` tool + data model** — New item type (e.g., `USER#{userId} | PROFILE#latest`) with structured fields useful for steering generation. Generated on-demand, cached.
5. **Gateway configuration** — Define final tool schemas (Draft 7), wire Lambdas, configure fine-grained access control rules in Gateway.

### Out of scope (explicitly)

- OData/REST export for non-MCP BI tools (not needed; Quick speaks MCP natively).
- Pre-computed batch recommendations (cost-prohibitive at scale; on-demand + cache is sufficient).
- Write/mutation tools (admin operations stay in the SPA).
- Raw prompt/response exposure via MCP (hard governance boundary).
- Changes to the existing SPA or its backend API (this is additive infrastructure).

### References

- Existing read handlers: `backend/handlers/usage_handler.py`, `account_usage_handler.py`, `recommendation_handler.py`, `recommendation_engine.py`, `engagement_handler.py`, `segmentation_engine.py`, `funnel_calculator.py`, `user_details_handler.py`
- Existing async pattern: `backend/handlers/correlation_worker.py`, `agent_correlation_handler.py`
- AgentCore agent: `agent/app/GitCorrelationAgent/`, `agent/agentcore/agentcore.json`
- AgentCore Gateway docs: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html
- Amazon Quick MCP integration: https://docs.aws.amazon.com/quick/latest/userguide/mcp-integration.html
- Quick MCP blog (6-step checklist): https://aws.amazon.com/blogs/machine-learning/integrate-external-tools-with-amazon-quick-agents-using-model-context-protocol-mcp/
- Spec-driven workflow: `.kiro/specs/` (this should start as a new spec, e.g. `.kiro/specs/mcp-analytics-server/`)

Start with the Quick Desktop ↔ AgentCore Gateway interoperability spike and the AgentCore Gateway documentation, using the existing agent/agentcore/agentcore.json and correlation_worker.py patterns. Review the listed handlers and the new .kiro/specs/mcp-analytics-server/ location before defining the work. Done means OAuth and claim propagation are validated with a trivial tool, followed by scoped read-only tools that preserve pending behavior and data isolation.

Written by the indexing model from the issue text.