docs: add MCP server support design proposal

[alexeykazakov]

Summary by CodeRabbit

Documentation

• Added comprehensive design documentation for MCP (Model Context Protocol) server support, including security specifications, configuration schema details, and implementation phases.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 19caeb16-eafd-4690-8c87-5df155e5e169

📥 Commits

Reviewing files that changed from the base of the PR and between 9eb7cb9 and 3e5a1a0.

📒 Files selected for processing (2)

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

📜 Recent 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/proposals/mcp-support-questions.md
• docs/proposals/mcp-support-design.md

🪛 LanguageTool

docs/proposals/mcp-support-questions.md

[grammar] ~22-~22: Ensure spelling is correct
Context: ...ier 2 — Stdio with proxy placeholder:** Stdio MCP subprocesses inherit HTTP_PROXY/`...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[grammar] ~43-~43: Ensure spelling is correct
Context: ...for well-known MCP servers. Tier 3 — Stdio with real secret (escape hatch): When...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[grammar] ~74-~74: Ensure spelling is correct
Context: ...ugh route. Stdio MCP server domains are allowlisted via credentials entries (which the us...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

docs/proposals/mcp-support-design.md

[grammar] ~13-~13: 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] ~33-~33: 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)

---

[grammar] ~254-~254: Ensure spelling is correct
Context: ... and claw_proxy_test.go ### Phase 2: Stdio MCP secret injection (tier 3 — escape h...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.22.1)

docs/proposals/mcp-support-design.md

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

(MD040, fenced-code-language)

🔇 Additional comments (2)

docs/proposals/mcp-support-design.md (1)

1-324: Excellent comprehensive design proposal.

This is a well-structured and thoroughly considered design for MCP server support. The three-tier security model is sound and pragmatic, balancing security (keeping secrets off the gateway when possible) with practical usability (providing an escape hatch for complex cases). Key strengths:

• Security-first approach: Tiers 1-2 preserve the proxy-based secret isolation model, with tier 3 as an explicit opt-in
• Phased implementation: Preventing premature API surface exposure by deferring envFrom to Phase 2 is smart
• Clear architecture: The reconciliation flow diagram and component integration points are well-documented
• Practical examples: The full CR example demonstrates all three tiers clearly

The design properly acknowledges documentation as a required deliverable (Phase 3) rather than follow-up work, which is important given the non-obvious proxy-placeholder pattern.

docs/proposals/mcp-support-questions.md (1)

1-206: Well-documented design decisions with clear rationale.

This companion document effectively captures the decision-making process behind the design. The Q&A format with explicit "considered and rejected" alternatives provides valuable context for future maintainers. The decisions are internally consistent and align well with the main design document.

Particularly strong points:

• Q1: The three-tier model with documented trade-offs and an explicit documentation requirement
• Q3: Auto-extraction for HTTP MCP URLs reduces API surface while solving the common case
• Q6: Appropriately scoped validation (only structurally certain rules) avoids over-constraining future OpenClaw evolution

---

Walkthrough

Two design documentation files added: mcp-support-questions.md resolving key design decisions (Q1–Q7) for MCP server support, and mcp-support-design.md providing a comprehensive technical specification for operator-managed MCP servers via a new spec.mcpServers CRD field, including security tiers, reconciliation flow, validation rules, and implementation phases.

Changes

MCP Server Support Design & Questions

Layer / File(s)	Summary
Design Decisions docs/proposals/mcp-support-questions.md	Resolves seven key design questions (Q1–Q7): three-tier secret model, proxy auth via headers, allowlisting behavior, spec.mcpServers CRD structure, env vs envFrom separation, validation scope, and McpServersConfigured status condition.
Technical Specification docs/proposals/mcp-support-design.md	Full design proposal covering security tiers (HTTP/SSE, stdio with proxy-placeholder, stdio with real secrets), reconciliation flow from CRD to proxy config, CRD schema additions (McpServerSpec, McpEnvFromSecret), CEL/reconciler validation rules, gateway env injection via envFrom, and three-phase implementation plan with example CR usage.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested labels

proposal, documentation

🚥 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 and concisely summarizes the main change: adding documentation for MCP server support design proposal.
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.}