Deprecated — Consolidated into DEV-0001 on 2026-05-02 per ADR-0047. This source file is retained as a reference; the canonical content is in DEV-0001.

ADR-0026: Claude Code Optimization and MCP Strategy¶

Date: 2026-04-06 Status: Accepted

Context¶

ADR-0021 established Claude Code as the platform AI developer assistant. After several weeks of active use, token costs reached ~$65/day running pure Opus 4.6. The platform needed a cost optimization strategy without sacrificing capability, plus a standardized way to give Claude Code context across all repos and connect it to external services via MCP.

Decision¶

Model configuration (~/.claude/settings.json)¶

Default model: claude-sonnet-4-6 — best quality/cost ratio for IaC tasks
Subagents: claude-haiku-4-5 — lightweight tasks, file reads, searches
Thinking budget: 10,000 tokens — sufficient for architecture decisions
Auto-compact: 50% threshold — prevents context overflow on long sessions
Statusline: cost display enabled — real-time spend visibility

Projected cost: under $15/day vs $65/day pure Opus — approximately 75% reduction.

Context portability — CLAUDE.md¶

All 6 repos have a CLAUDE.md at root that: 1. Points to archon-docs/docs/_context.md as the primary AI context source 2. Declares repo-specific scope and constraints 3. Is the first file Claude Code reads on session start

Global ~/.claude/CLAUDE.md provides baseline identity and platform context. No Memory MCP needed — generate-context.py pipeline auto-refreshes _context.md on every push to archon-docs main.

MCP servers¶

Server	Package	Scope	Auth
Azure DevOps	@tiberriver256/mcp-server-azure-devops	archon-platform repo (.mcp.json)	PAT (project-scoped)
Azure Infrastructure	@azure/mcp	Global (~/.claude/)	Azure CLI credentials

ADO MCP config lives in archon-platform/.mcp.json — not global, scoped to platform IaC work. Microsoft official ADO MCP OAuth not yet supported in Claude Code as of April 2026 — PAT used as interim solution.

Usage tracking¶

ccusage CLI installed — token and cost reporting
Daily cron at 23:[REDACTED] exports claude-usage-30d.json to ~/homelab/data/claude-usage/
Planned: Node-RED → InfluxDB → Grafana dashboard for cost visualization (WI created)

settings.local.json hygiene¶

archon-platform/.claude/settings.local.json: trimmed to 25 generic permission entries
~/homelab/.claude/settings.local.json: trimmed to 16 entries
Removed: hardcoded credentials, PR-specific one-liners, repo-specific paths
Pattern: keep only generic tool permission grants

Why MCP¶

MCP servers were not chosen purely for convenience. They are the programmatic layer that makes AI portability real. Any model connecting to these MCPs gets live platform state -- current cluster status, pipeline runs, secrets metadata, DNS config -- not stale context from a previous session.

This ties directly to the AI portability philosophy documented in docs/reference/ai-portability.md. The pattern is the same as CLAUDE.md and _context.md: every layer of the platform is designed so that context is reconstructible, not dependent on a single session, a single model, or a single operator remembering things.

MCP is the runtime expression of that principle. ADRs and _context.md are the static expression. Together they form the AI portability stack.

Backlog items identified¶

Item	Priority
.claudeignore in all 6 repos — reduce cache read token burn	High
Cloudflare MCP — replace curl API one-liners	Medium
Audit settings.local.json in archon-apps, archon-cloud, archon-pipelines, archon-web	Medium
Agent architecture — architecture, code reviewer, security reviewer agents	Low

Consequences¶

Significant cost reduction while maintaining capability for complex IaC tasks
CLAUDE.md must be kept current when platform state changes significantly
PAT for ADO MCP must be rotated per standard rotation runbook (docs/internal/secret-rotation.md)
Cloudflare MCP identified as next MCP addition — replaces curl one-liners for DNS/Pages/Workers
Agent architecture (architecture agent, COO/CIO layer, code reviewer, security reviewer) planned as future optimization

Supersedes¶

Extends ADR-0021 (Claude Code IaC authoring) with operational optimization decisions. ADR-0021 remains valid for scope and boundary decisions.

ADR-0021: Claude Code as developer tooling
ADR-0011: Claude Code developer tooling boundary
ADR-0014: Ansible service account (ansible-svc-account pattern applied to MCP auth)