docs: add Claude Code configuration and troubleshooting guide

- Add Claude Code section with tested JSON configuration command
- Include troubleshooting guidance for stdio transport connection issues
- Explain that health check failures are normal but don't affect functionality
- Document proper environment variable handling for KUBECONFIG
- Provide user-level scope installation for cross-project availability

Resolves common 'Failed to connect' issues by using JSON format instead of command-line args

Author: rafilkmp3

README.md

@@ -128,6 +128,31 @@ extensions:
 
 ```
 
+### Claude Code
+
+[Claude Code](https://claude.ai/code) provides an integrated command-line interface for Claude with MCP server support.
+
+For reliable connection with Claude Code, use the JSON configuration format:
+
+```bash
+claude mcp add-json kubectl '{"command":"npx","args":["-y","kubernetes-mcp-server@latest"],"env":{"KUBECONFIG":"${HOME}/.kube/config"}}' -s user
+```
+
+This ensures:
+- ✅ Reliable stdio transport connection
+- ✅ User-level scope (works across all projects) 
+- ✅ Proper environment variable handling
+- ✅ Auto-managed server lifecycle
+
+#### Troubleshooting
+
+If you see "Failed to connect" in health checks but the server works when you run kubectl commands, this is expected behavior. The health check timeout may be too aggressive for stdio transport, but the server will function correctly when Claude Code actually uses it.
+
+For connection issues, ensure you're using:
+- **JSON format**: Use `claude mcp add-json` with proper JSON structure instead of command-line arguments
+- **Separate args array**: `"args":["-y","kubernetes-mcp-server@latest"]` instead of combined strings
+- **Environment variables**: Set `KUBECONFIG` in the `env` object for proper kubectl access
+
 ## 🎥 Demos <a id="demos"></a>
 
 ### Diagnosing and automatically fixing an OpenShift Deployment