Merge pull request #40 from KeeperHub/chore/deprecate-serve-mcp

chore: deprecate kh serve --mcp in favor of remote HTTP MCP

Author: eskp

README.md

@@ -38,11 +38,15 @@ kh protocol list                   # Browse available protocols
 
 ## MCP Server Mode
 
+The recommended way to connect AI assistants to KeeperHub is the remote HTTP endpoint:
+
 ```
-kh serve --mcp
+claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp
 ```
 
-Starts an MCP server that exposes KeeperHub actions as tools to AI assistants such as Claude Desktop. See [docs/quickstart.md](docs/quickstart.md) for setup instructions.
+No local server process required. See [docs/quickstart.md](docs/quickstart.md) for full setup instructions.
+
+The legacy `kh serve --mcp` stdio mode is still available but deprecated.
 
 ## Documentation
 

cmd/root_test.go

@@ -154,7 +154,7 @@ func TestRootCmdHelpIncludesAllCommands(t *testing.T) {
 		"workflow", "run", "execute", "project",
 		"tag", "org", "action", "protocol",
 		"wallet", "template", "billing", "doctor",
-		"version", "auth", "config", "serve", "completion", "update",
+		"version", "auth", "config", "completion", "update",
 	}
 	for _, cmdName := range expectedCommands {
 		assert.True(t, strings.Contains(helpOutput, cmdName),

cmd/serve/serve.go

@@ -24,7 +24,8 @@ All diagnostic output (warnings, errors) is written to stderr. Only
 valid JSON-RPC 2.0 messages appear on stdout.`,
 		Example: `  # Start an MCP stdio server (for use with Claude, Cursor, etc.)
   kh serve --mcp`,
-		Args: cobra.NoArgs,
+		Deprecated: "Use the remote MCP endpoint instead: claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp",
+		Args:       cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			isMCP, err := cmd.Flags().GetBool("mcp")
 			if err != nil {

docs/kh_serve.md

@@ -2,6 +2,12 @@
 
 Start a server
 
+**Deprecated:** Use the remote MCP endpoint instead:
+
+```
+claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp
+```
+
 ### Synopsis
 
 Start a KeeperHub server process.
@@ -44,4 +50,3 @@ kh serve [flags]
 ### SEE ALSO
 
 * [kh](kh.md)	 - KeeperHub CLI
-

docs/quickstart.md

@@ -58,20 +58,24 @@ kh protocol list
 
 ## MCP Server Mode
 
-The CLI can act as an [MCP](https://modelcontextprotocol.io) server, exposing KeeperHub actions as tools to AI assistants.
+KeeperHub exposes its actions as tools to AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io).
 
-**Start the MCP server:**
+**Recommended: remote HTTP endpoint (no local server required):**
 ```
-kh serve --mcp
+claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp
 ```
 
 **Add to Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
-{ "mcpServers": { "keeperhub": { "command": "kh", "args": ["serve", "--mcp"] } } }
+{ "mcpServers": { "keeperhub": { "type": "http", "url": "https://app.keeperhub.com/mcp" } } }
 ```
 
 Restart Claude Desktop. KeeperHub tools will appear in the tool list.
 
+**Legacy: local stdio server (deprecated):**
+
+`kh serve --mcp` starts a local MCP stdio server. This mode is deprecated. Prefer the remote HTTP endpoint above.
+
 ## Next Steps
 
 - [concepts.md](concepts.md) -- authentication, output formats, configuration