[PROPOSAL] Native MCP Server for AI-Driven Operator Development

[vitorfloriano]

What do you want to happen?

Summary

This proposal suggests integrating a native Model Context Protocol (MCP) server into the kubebuilder binary. This transforms Kubebuilder from a static CLI into a discoverable capability provider. By doing so, we can eliminate the manual overhead of managing AGENTS.md files and custom prompts, allowing MCP-compliant AI assistants (Cursor, Claude Code, Copilot, etc.) to discover Kubebuilder’s commands, best practices, and project context directly through a standardized protocol.

The Problem: "Instruction Rot" & Context Friction

Currently, to get high-quality assistance from AI when building an operator, users must:

• Manually Provide Context: decide which files to include as context into the chat with the assistant.
• Manage Instructions: Maintain files like AGENTS.md to "teach" the AI how to use the Kubebuilder CLI.
• Handle "Prompt Rot": As Kubebuilder and controller-runtime evolve, these manual instructions become outdated. Users must manually check for updates and sync their prompts.

❗ We are currently teaching users how to teach AIs. We should instead allow the binary to expose its knowledge directly.

The Proposal: kubebuilder mcp

We propose adding a kubebuilder mcp subcommand. This server could provide core capabilities to any MCP-compliant AI assistant, like the following:

• Resources (Live Project Context)
  Instead of users uploading files, the binary serves project state as URIs. For example:
  kubebuilder://project/config: Returns the current PROJECT metadata.
  kubebuilder://project/apis: Provides a summarized view of the current GVK structure.
  Benefit: The AI always has "ground truth" context without user intervention.

• Prompts (Embedded Best Practices)
  Kubebuilder exposes versioned, domain-specific prompt content directly from the binary.
  Example: A reconcile-loop prompt describing idiomatic, production-ready controller patterns for the specific Kubebuilder version in use.
  Benefit: Updating Kubebuilder automatically updates the exposed guidance, keeping AI-assisted workflows aligned with the current release.

• Tools (Actionable Scaffolding)
  Expose Kubebuilder commands (init, create api, edit) as MCP Tools.
  Benefit: The AI can suggest and with user approval execute scaffolding commands directly, ensuring it uses the correct flags and plugins every time.

Strategic Advantage: Discoverability & Versioning

The primary advantage of a native MCP server over the current AGENTS.md is automatic synchronization:

• Versioning: An AI interacting with Kubebuilder v4.7.1 would be able to receive different guidance than one interacting with v4.11.0.
• Zero-Config: Users don't need to copy/paste prompts or maintain AI instructions. They simply point their AI to the kubebuilder mcp command, and the AI "discovers" everything it can do.

Why Now is The Best Time

• Standardization: MCP is no longer proprietary; it is governed by the Linux Foundation through the AAIF. While still in its early days, it has received broad backing from multiple companies.
• Tooling: The official Go SDK for MCP, which is maintained in collaboration with Google, has reached stability and is being actively developed, providing a reliable foundation.
• Shift in Industry: As more developers move to AI-assisted coding, Kubebuilder needs to provide a first-class integration point for AI-assisted development workflows.

💡Mentorship Opportunity

Given the innovative nature of this project, this can be an ideal candidate for a mentorship (LFX/GSoC) project. It has a well-defined scope and is high-impact. The mentee will work with a modern protocol, CLI design in Go, and Kubernetes operator patterns.

Extra Labels

No response

[camilamacedo86]

Hi @vitorfloriano,

Thanks for raising this. I agree it’s worth exploring a native MCP integration in Kubebuilder.

That said, MCP does not remove the need for AGENTS.md (or repo docs). They solve different problems:

• MCP is best for discoverability + runtime context:

  • expose Kubebuilder commands/flags/plugins/scaffolding as discoverable tools
  • surface project/cluster signals to help with troubleshooting
  • provide a few repeatable workflows (e.g., scaffold, verify, diagnose)

• AGENTS.md is best for solution-development context (repo/org specific):

  • architecture and preferred patterns
  • coding conventions, repo structure, review expectations
  • workflows (tests/CI), regeneration rules, “definition of done”

Also, docs still matter even with MCP. Not everyone will use an MCP-capable client, and many users will interact with “any AI” (Claude, Gemini, Copilot, etc.) where MCP may not be available/enabled. Docs are also a good place to include AI instruction templates (e.g., a Claude-style command) to help users complete one-time tasks safely instead of following long manual checklists.

In that sense, using MCP does not remove the need for AGENTS.md.
Also, MCP isn’t a replacement for providing AI instructions for operational and repetitive tasks—especially the ones we want to define once, but that are hard to automate cleanly with a shell script. For those cases, AI can be a better fit because it can reason over context and handle variations, rather than following a rigid script.

How to move forward

1. PoC: a small PR/prototype that we can run locally to demonstrate a few concrete flows (discover commands, scaffold/generate, troubleshoot using cluster/project context).
2. Answer the design questions (issue or design doc): client support, when MCP is/isn’t available + fallbacks, UX, security/permissions, maintenance/versioning, and a clear v1 scope.

If MCP ends up covering most real user workflows, we can consider adding it to the default scaffold. Otherwise, shipping it as an optional plugin/add-on still delivers value for early adopters.

Thanks,
Camila

[camilamacedo86]

Hi @vitorfloriano

Btw, I thought AMAZING your proposal.
We really MUST to check and explore all options to make the tooling smarter and take advantage of AI.