AWS CloudWatch MCP Integration Plan

Objectives

• Vendor the AWS Labs CloudWatch MCP server so Sasha can inspect metrics, alarms, and logs via a curated MCP interface.
• Reuse the AWS Cost integration playbook (wrapper scripts, smoke tests, Claude CLI registration, encrypted config storage).
• Apply lessons learned: ship uv binaries properly, vendor smoke-test dependencies, and keep operator guidance self-contained.

---

Runtime Strategy

1. Vendored assets (integrations/mcp/aws-cloudwatch/)

   • README.md summarizing upstream repo, tool catalog, and IAM prerequisites.
   • UPSTREAM_COMMIT pinning the cloudwatch-mcp-server version.
   • run-aws-cloudwatch-mcp.sh wrapper → uvx awslabs.cloudwatch-mcp-server@latest (stdio transport).
   • smoke-test.js (Node ESM) that connects via MCP and exercises a safe tool (e.g., get_metric_metadata or describe_log_groups). Handle missing tools gracefully.
   • package.json + package-lock.json for the smoke harness (depends on @modelcontextprotocol/sdk); Docker builder runs npm ci && npm prune --omit=dev.

2. Dockerfile updates (claudecodeui/Dockerfile.sliplane)

   • Install uv in both builder and runner stages using install -m755 /root/.local/bin/uv{,x} /usr/local/bin/ (no symlinks to /root/.local).
   • Copy the CloudWatch integration dir into the builder stage and run npm ci (even though runtime uses uvx).
   • Ensure runtime stage copies the integration directory (including node_modules/).

---

Backend Service & Routes

1. Service module claudecodeui/server/services/awsCloudWatchMcpService.js

   • Config path: /home/sasha/config/mcp/aws-cloudwatch.json.
   • Persist encrypted accessKeyId/secretKey/sessionToken, region, optional default log group/namespace, lastTest.
   • registerServer() uses claude mcp add -s user aws-cloudwatch ... --env AWS_REGION=... --env AWS_ACCESS_KEY_ID=... --env AWS_SECRET_ACCESS_KEY=... --env FASTMCP_LOG_LEVEL=ERROR.
   • removeServer(), getStatus(), runSmokeTest() mirror AWS Cost service. Smoke test should log available tools/snippet even if specific tool isn’t present.

2. Routes claudecodeui/server/routes/mcp-aws-cloudwatch.js

   • GET /status, POST /configure, POST /register, DELETE /register, POST /test.
   • Input validation: ensure AWS access key ID + secret (optional session token) are present before saving.

3. Wire-up

   • Mount router in server/routes/mcp.js (router.use('/aws-cloudwatch', awsCloudWatchRouter);).
   • Update toolStatusService.js to map 'aws-cloudwatch-tool' → 'aws-cloudwatch'.

---

UI Changes

1. State hooks in ToolsSettings.jsx

   • awsCloudWatchStatus, awsCloudWatchForm, awsCloudWatchAction, awsCloudWatchMessage/Error/TestResult.
   • Derived flags: hasCloudWatchKeys, cloudWatchConfigured.

2. Integration card

   • Title: “AWS CloudWatch Observability”.
   • Inputs:
     • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, optional AWS_SESSION_TOKEN.
     • Region dropdown (default us-east-1).
     • Optional defaults: log group, metric namespace.
   • Operator guidance block:
     • Step-by-step instructions to enable IAM billing access, Cost Explorer, Cost Optimization Hub, and Compute Optimizer (with CLI snippets).
     • Attach AWS-managed policies (job-function/Billing, ComputeOptimizerReadOnlyAccess, AWSTrustedAdvisorReadOnlyAccess).
     • Optional Storage Lens/Athena policy JSON for bucket access.
   • Buttons: Save, Register, Remove, Test; smoke output panel with 500-char snippet.

3. Summaries & cards

   • Extend integrationSummaries with aws-cloudwatch status logic (needs creds, ready, connected).
   • Add card entry to integrationCards.

4. Chat UI

   • Update ChatInterface.jsx MCP_TOOL_PREFIXES with { id: 'aws-cloudwatch-tool', label: 'CloudWatch', prefix: 'CloudWatch: ' }.

---

Docs & Operator Guidance

1. Tool doc deployed-md-files/docs/tools/aws-cloudwatch-tool.md

   • Describe capabilities (metrics, alarms, logs), prerequisites, example prompts.

2. Docs index add CloudWatch entry with emoji + example.

3. Tech plan (this file) stored at docs/tech/aws-cloudwatch-mcp-plan.md.

4. Setup guide docs/tech/aws-cloudwatch-setup.md

   • Managed policy instructions, prerequisites, optional custom policy snippet.

5. Integration overview (claudecodeui/docs/integrations/mcp-integration-approach.md) add CloudWatch section.

---

IAM & Security Notes

• Recommended managed policies: arn:aws:iam::aws:policy/job-function/Billing, arn:aws:iam::aws:policy/ComputeOptimizerReadOnlyAccess, arn:aws:iam::aws:policy/AWSTrustedAdvisorReadOnlyAccess.
• Additional log permissions: logs:DescribeLogGroups, logs:DescribeQueryDefinitions, logs:ListLogAnomalyDetectors, logs:ListAnomalies, logs:StartQuery, logs:GetQueryResults, logs:StopQuery.
• Optional Storage Lens/Athena access for Storage Lens tools.
• UI accepts explicit access keys only (simplifies operator workflow).
• Enforce least privilege; rotate keys and re-run smoke tests after each rotation.

---

Testing & Verification

1. Local

   • bash run-aws-cloudwatch-mcp.sh --help to verify uvx wrapper.
   • node smoke-test.js with sandbox env (exercise a descriptive tool like get_metric_metadata).

2. Application

   • Configure via UI with sandbox access keys.
   • Save → Test → Register; inspect UI status and backend logs.
   • In chat, run sample prompts (alarms, metrics, logs).

3. Deployment

   • Rebuild Docker image; confirm /usr/local/bin/uv + /usr/local/bin/uvx exist and have 755 perms.
   • Ensure /home/sasha/config/mcp/aws-cloudwatch.json persists on the mounted volume.
   • claude mcp list shows aws-cloudwatch with a .

---

Lessons Applied / Checklist

• Install uv binaries using install -m755 … in both builder + runner stages.
• Vendor smoke-test dependencies (package.json + npm ci) so @modelcontextprotocol/sdk is present in the container.
• Smoke test should log available tools and not crash when a specific tool is absent.
• UI instructions include managed policy approach + prerequisites (IAM billing access, Cost Explorer, Cost Optimization Hub, Compute Optimizer).
• Keep documentation (tool guide + setup guide) updated alongside the implementation.