chore: deprecate hexai-mcp-server as experimental

Add deprecation notices across hexai-mcp-server codebase and documentation.
The MCP server is now considered experimental and not actively maintained,
as prompts are managed through slash commands and meta-commands instead.

Changes:
- Add runtime deprecation warning to stderr on binary startup
- Mark feature as deprecated in README.md
- Add deprecation notices to all 8 MCP documentation files
- Add deprecation log message to run.go
- Update Magefile.go build comment

The code remains fully functional but warns users of its experimental status.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

12 files changed, 129 insertions, 4 deletions

diff --git a/MCP-SERVER-PLAN.md b/MCP-SERVER-PLAN.md
index 133ee69..97032a6 100644
--- a/MCP-SERVER-PLAN.md
+++ b/MCP-SERVER-PLAN.md
@@ -1,5 +1,17 @@
 # Plan: hexai-mcp-server - MCP Server for Prompts and Runbooks
 
+> **⚠️ DEPRECATION NOTICE**
+>
+> This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**.
+>
+> The author currently manages prompts through slash commands and meta-commands
+> in the hexai agent system, making this MCP server redundant for its original
+> purpose. This code is kept for potential future enhancements (possibly with
+> different functionality beyond prompt management), but no guarantees are made
+> about stability or continued support.
+>
+> **This documentation is preserved for reference only.**
+
 ## Context
 
 This change adds a new MCP (Model Context Protocol) server to hexai for managing prompts and runbooks. Currently, hexai has prompts hardcoded in the configuration file, making it difficult to share, version, and dynamically manage reusable prompts. An MCP server provides a standardized protocol for AI agents (like Claude Code CLI, Cursor) to discover and use prompts/runbooks from hexai.
diff --git a/Magefile.go b/Magefile.go
index bea6b1f..4d79079 100644
--- a/Magefile.go
+++ b/Magefile.go
@@ -53,7 +53,7 @@ func BuildHexaiTmuxEdit() error {
 	return sh.RunV("go", "build", "-o", "hexai-tmux-edit", "cmd/hexai-tmux-edit/main.go")
 }
 
-// BuildHexaiMCPServer builds the MCP server binary.
+// BuildHexaiMCPServer builds the MCP server binary (DEPRECATED - experimental, not actively maintained).
 func BuildHexaiMCPServer() error {
 	printCoverage()
 	return sh.RunV("go", "build", "-o", "hexai-mcp-server", "cmd/hexai-mcp-server/main.go")
diff --git a/README.md b/README.md
index 305853b..2e92db2 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ It has got improved capabilities for Go code understanding (for example, create
 * LSP in-editor chat with the LLM
 * Stand-alone command line tool for LLM interaction
 * Parallel completions and CLI responses from multiple providers/models for side-by-side comparison
-* **MCP server for prompt/runbook management** (`hexai-mcp-server`)
+* **MCP server for prompt/runbook management** (`hexai-mcp-server`) - **⚠️ DEPRECATED/EXPERIMENTAL**
   - Create, update, delete, and retrieve prompts via MCP protocol
   - Automatic backups on every change (keeps last 10)
   - Compatible with Claude Code CLI, Cursor, and other MCP clients
@@ -27,14 +27,16 @@ It has got improved capabilities for Go code understanding (for example, create
   - Config-driven: add new agents via `[tmux_edit]` in config.toml
 * Support for OpenAI, OpenRouter, Anthropic, and Ollama
 
+> **Note on hexai-mcp-server:** This component is currently experimental and not actively maintained. The author manages prompts through slash commands and meta-commands in the hexai agent system, making the MCP server redundant for its original purpose. The code is preserved for potential future enhancements with different functionality beyond prompt management. See the [MCP documentation](docs/mcp-setup.md) for reference only.
+
 ## Documentation
 
 * [Build and install guide](docs/buildandinstall.md)
 * [Configuration guide](docs/configuration.md)
 * [Usage examples](docs/usage.md)
 * [Helix + tmux quickstart](docs/tmux.md)
-* [MCP server setup guide](docs/mcp-setup.md)
-* [Creating custom prompts](docs/mcp-prompts.md)
+* [MCP server setup guide](docs/mcp-setup.md) *(deprecated - reference only)*
+* [Creating custom prompts](docs/mcp-prompts.md) *(deprecated - reference only)*
 
 ## Tmux Status Line
 
diff --git a/cmd/hexai-mcp-server/main.go b/cmd/hexai-mcp-server/main.go
index acdb1d0..557172f 100644
--- a/cmd/hexai-mcp-server/main.go
+++ b/cmd/hexai-mcp-server/main.go
@@ -12,7 +12,33 @@ import (
 	"codeberg.org/snonux/hexai/internal/hexaimcp"
 )
 
+// printDeprecationWarning outputs a deprecation notice to stderr explaining
+// that hexai-mcp-server is experimental and not actively maintained.
+func printDeprecationWarning() {
+	warning := `
+⚠️  DEPRECATION NOTICE ⚠️
+
+hexai-mcp-server is currently EXPERIMENTAL and NOT ACTIVELY MAINTAINED.
+
+The author does not have a real use case for this MCP server at this time.
+Prompts are now managed through slash commands and meta-commands in the
+main hexai agent system, making this MCP server's prompt management
+functionality redundant.
+
+This code is kept in the repository for potential future enhancements
+(possibly adding more useful functionality than prompt management), but
+no guarantees are made about its stability or continued support.
+
+Use at your own risk.
+
+────────────────────────────────────────────────────────────────────────
+`
+	fmt.Fprintln(os.Stderr, warning)
+}
+
 func main() {
+	printDeprecationWarning()
+
 	defaultLog := defaultLogPath()
 	logPath := flag.String("log", defaultLog, "path to log file (optional)")
 	configPath := flag.String("config", "", "path to config file (optional)")
diff --git a/docs/mcp-api.md b/docs/mcp-api.md
index 5157c42..a1d0f8c 100644
--- a/docs/mcp-api.md
+++ b/docs/mcp-api.md
@@ -1,5 +1,17 @@
 # MCP Server API Reference
 
+> **⚠️ DEPRECATION NOTICE**
+>
+> This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**.
+>
+> The author currently manages prompts through slash commands and meta-commands
+> in the hexai agent system, making this MCP server redundant for its original
+> purpose. This code is kept for potential future enhancements (possibly with
+> different functionality beyond prompt management), but no guarantees are made
+> about stability or continued support.
+>
+> **This documentation is preserved for reference only.**
+
 The hexai-mcp-server implements the Model Context Protocol with prompt management extensions.
 
 ## Protocol Version
diff --git a/docs/mcp-automatic-backups.md b/docs/mcp-automatic-backups.md
index 87ec329..22469d3 100644
--- a/docs/mcp-automatic-backups.md
+++ b/docs/mcp-automatic-backups.md
@@ -1,5 +1,17 @@
 # MCP Server Automatic Backups
 
+> **⚠️ DEPRECATION NOTICE**
+>
+> This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**.
+>
+> The author currently manages prompts through slash commands and meta-commands
+> in the hexai agent system, making this MCP server redundant for its original
+> purpose. This code is kept for potential future enhancements (possibly with
+> different functionality beyond prompt management), but no guarantees are made
+> about stability or continued support.
+>
+> **This documentation is preserved for reference only.**
+
 ## ✅ Fully Automatic - No Manual Tools Required!
 
 The hexai-mcp-server automatically creates backups **on every write operation**. You don't need any CLI tools - everything happens automatically when you use the MCP protocol.
diff --git a/docs/mcp-features-summary.md b/docs/mcp-features-summary.md
index 090b616..d5e7f19 100644
--- a/docs/mcp-features-summary.md
+++ b/docs/mcp-features-summary.md
@@ -1,5 +1,17 @@
 # hexai-mcp-server Complete Feature Summary
 
+> **⚠️ DEPRECATION NOTICE**
+>
+> This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**.
+>
+> The author currently manages prompts through slash commands and meta-commands
+> in the hexai agent system, making this MCP server redundant for its original
+> purpose. This code is kept for potential future enhancements (possibly with
+> different functionality beyond prompt management), but no guarantees are made
+> about stability or continued support.
+>
+> **This documentation is preserved for reference only.**
+
 ## 🎯 Overview
 
 The hexai-mcp-server is a complete Model Context Protocol implementation with prompt management capabilities. It includes both **standard MCP methods** and **management extensions** that allow full CRUD operations on prompts.
diff --git a/docs/mcp-managing-prompts.md b/docs/mcp-managing-prompts.md
index 675e0c8..7cca112 100644
--- a/docs/mcp-managing-prompts.md
+++ b/docs/mcp-managing-prompts.md
@@ -1,5 +1,17 @@
 # Managing MCP Prompts
 
+> **⚠️ DEPRECATION NOTICE**
+>
+> This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**.
+>
+> The author currently manages prompts through slash commands and meta-commands
+> in the hexai agent system, making this MCP server redundant for its original
+> purpose. This code is kept for potential future enhancements (possibly with
+> different functionality beyond prompt management), but no guarantees are made
+> about stability or continued support.
+>
+> **This documentation is preserved for reference only.**
+
 Quick reference for managing hexai MCP server prompts.
 
 ## 🚀 All Management Through MCP Protocol
diff --git a/docs/mcp-prompts.md b/docs/mcp-prompts.md
index 260760b..a12385c 100644
--- a/docs/mcp-prompts.md
+++ b/docs/mcp-prompts.md
@@ -1,5 +1,17 @@
 # MCP Prompts Guide
 
+> **⚠️ DEPRECATION NOTICE**
+>
+> This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**.
+>
+> The author currently manages prompts through slash commands and meta-commands
+> in the hexai agent system, making this MCP server redundant for its original
+> purpose. This code is kept for potential future enhancements (possibly with
+> different functionality beyond prompt management), but no guarantees are made
+> about stability or continued support.
+>
+> **This documentation is preserved for reference only.**
+
 ## Overview
 
 Prompts in hexai-mcp-server are reusable templates that can be parameterized with arguments. They're stored in JSONL format (one JSON object per line) for easy editing and version control.
diff --git a/docs/mcp-server-complete.md b/docs/mcp-server-complete.md
index 5d8d7ca..8d08e9d 100644
--- a/docs/mcp-server-complete.md
+++ b/docs/mcp-server-complete.md
@@ -1,5 +1,17 @@
 # hexai-mcp-server: Complete Solution
 
+> **⚠️ DEPRECATION NOTICE**
+>
+> This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**.
+>
+> The author currently manages prompts through slash commands and meta-commands
+> in the hexai agent system, making this MCP server redundant for its original
+> purpose. This code is kept for potential future enhancements (possibly with
+> different functionality beyond prompt management), but no guarantees are made
+> about stability or continued support.
+>
+> **This documentation is preserved for reference only.**
+
 ## Overview
 
 The hexai-mcp-server is a **fully self-contained MCP server** that manages prompts entirely through the protocol. No additional tools needed!
diff --git a/docs/mcp-setup.md b/docs/mcp-setup.md
index 6f75cb9..c1e966b 100644
--- a/docs/mcp-setup.md
+++ b/docs/mcp-setup.md
@@ -1,5 +1,17 @@
 # MCP Server Setup Guide
 
+> **⚠️ DEPRECATION NOTICE**
+>
+> This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**.
+>
+> The author currently manages prompts through slash commands and meta-commands
+> in the hexai agent system, making this MCP server redundant for its original
+> purpose. This code is kept for potential future enhancements (possibly with
+> different functionality beyond prompt management), but no guarantees are made
+> about stability or continued support.
+>
+> **This documentation is preserved for reference only.**
+
 ## What is MCP?
 
 Model Context Protocol (MCP) is a standardized protocol for AI agents to discover and use prompts, tools, and resources from external servers. The `hexai-mcp-server` provides a prompt management system that works with any MCP-compatible agent like Claude Code CLI, Cursor, or other AI coding assistants.
diff --git a/internal/hexaimcp/run.go b/internal/hexaimcp/run.go
index 5f687f1..23faa08 100644
--- a/internal/hexaimcp/run.go
+++ b/internal/hexaimcp/run.go
@@ -61,6 +61,7 @@ func RunWithFactory(
 	}()
 
 	logger.Printf("hexai-mcp-server starting")
+	logger.Printf("WARNING: hexai-mcp-server is DEPRECATED and experimental - not actively maintained")
 
 	// Load configuration
 	cfg := loadConfig(logger, configPath)