docs: promote MCP support proposal to ADR-0008

[alexeykazakov]

• Distill design doc and questions doc into an architecture decision record
• Consolidate all 7 design questions into a decisions table with rationale
• Remove implementation details (file paths, Go structs, phase checklists)
• Delete docs/proposals/mcp-support-{design,questions}.md

Summary by CodeRabbit

• Documentation
  • Added Architecture Decision Record documenting MCP server management design, including declarative configuration models, credential security patterns, and validation rules
  • Clarified operator reconciliation workflows for MCP server configuration and status tracking
  • Consolidated design specifications from proposal phase into finalized documentation

[coderabbitai]

Walkthrough

This PR consolidates MCP (Model Context Protocol) server support design documentation from two proposal files into ADR-0008. The ADR specifies the spec.mcpServers schema, three-tier secret-handling model (HTTP proxy credentials, stdio placeholders, envFrom escape hatch), operator reconciliation and validation flow, and introduces the McpServersConfigured status condition with a complete CR example.

Changes

MCP Support Architecture Documentation

Layer / File(s)	Summary
ADR-0008 Design Document docs/adr/0008-mcp-support.md	New ADR documenting declarative MCP server management: spec.mcpServers schema, three-tier secret handling, reconciliation/validation steps, McpServersConfigured condition, and example Claw CR with HTTP, stdio placeholder, and stdio real-secret configurations.
Removed Proposal Documents docs/proposals/mcp-support-design.md, docs/proposals/mcp-support-questions.md	Consolidated proposal and design-questions files are removed; content migrated into ADR-0008 for centralized design decision documentation.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• codeready-toolchain/claw-operator#113: Implements the spec.mcpServers declarative support design documented in this ADR.
• codeready-toolchain/claw-operator#114: Implements the envFrom escape-hatch, validation, and McpServersConfigured condition documented in the ADR.
• codeready-toolchain/claw-operator#112: Added the proposal and design-questions documents that this PR consolidates into an ADR.

Suggested labels

documentation, proposal

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: promoting MCP support documentation from proposal files into a formal ADR-0008, which aligns with the changeset of adding the ADR and removing proposal files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/adr/0008-mcp-support.md`:
- Around line 59-92: The fenced flow diagram block that begins with "Claw CR
spec.mcpServers" and ends at "merge.js (init-config at pod start)" is missing a
Markdown language tag; update the opening fence (the triple backticks before
that diagram) to include a language identifier such as text (e.g., change ``` to
```text) so the block passes MD040 linting and remains otherwise unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: acd48a74-ca7b-463e-bdc1-3ef3bac9282e

📥 Commits

Reviewing files that changed from the base of the PR and between a33a9a8 and 033dcbc.

📒 Files selected for processing (3)

• docs/adr/0008-mcp-support.md
• docs/proposals/mcp-support-design.md
• docs/proposals/mcp-support-questions.md

💤 Files with no reviewable changes (2)

• docs/proposals/mcp-support-questions.md
• docs/proposals/mcp-support-design.md

📜 Review details

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

-Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity.

Files:

• docs/adr/0008-mcp-support.md

🪛 LanguageTool

docs/adr/0008-mcp-support.md

[grammar] ~14-~14: Ensure spelling is correct
Context: ...servers are recommended over stdio. For stdio, a proxy-placeholder pattern keeps secr...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[grammar] ~46-~46: Ensure spelling is correct
Context: ...o secrets on the gateway. Tier 2 — Stdio MCP subprocesses inherit HTTP_PROXY/`...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.22.1)

docs/adr/0008-mcp-support.md

[warning] 59-59: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (1)

docs/adr/0008-mcp-support.md (1)

24-217: Solid ADR consolidation and decision traceability

The decisions table, tiered security model, reconciliation flow, validation split (CEL vs reconciler), and end-to-end CR example read consistently and make this ADR actionable for implementation and operations.