Dynamic URL Support and Kubernetes Deployment Enhancements

[dustinblack]

Overview

This PR adds dynamic URL configuration support and comprehensive Kubernetes deployment capabilities to the Elasticsearch MCP server, enabling multi-cluster and multi-tenant scenarios without server restarts.

Summary of Changes

Core Features

• Dynamic URL Support: Elasticsearch cluster URL can now be specified per-request via X-Elasticsearch-URL HTTP header
• Optional URL Configuration: URL defaults to http://localhost:9200 if not configured
• Dynamic Authentication: Support for both API Key and Basic authentication via headers
• Kubernetes-Ready: Full environment variable support for containerized deployments

Technical Changes

Backend (6 files, 433 lines changed)

• Made Elasticsearch URL optional in configuration with sensible defaults
• Enhanced EsClientProvider to dynamically build clients with custom URLs and credentials
• Added ENABLE_SSE environment variable support for SSE transport
• Implemented comprehensive logging for startup config and dynamic overrides
• Updated built-in default configuration to include default URL

Documentation (324 lines added)

• Added "Dynamic URL and Authentication" section explaining the feature
• Documented SSE transport setup with --sse flag
• Added client-specific configurations for Claude Desktop, Cursor, and Gemini
• Created comprehensive Kubernetes deployment guide with example YAML manifests
• Included examples for API Key and Basic authentication
• Added environment variable configuration guide

Use Cases

This enhancement enables:

• Multi-cluster access: Connect to different Elasticsearch clusters per request
• Multi-tenant scenarios: Different credentials for different operations
• Kubernetes deployments: Easy deployment without command-line argument restrictions
• Development flexibility: No need to restart server when switching clusters

Configuration Examples

Dynamic URL via Header

curl -H "X-Elasticsearch-URL: https://my-cluster.es.io:9200" \
     -H "Authorization: ApiKey <key>" \
     http://localhost:8080/mcp

Kubernetes Deployment

env:
- name: ENABLE_SSE
  value: "true"
- name: CONTAINER_MODE
  value: "true"
- name: ES_URL
  value: "http://elasticsearch:9200"

Backward Compatibility

✅ Fully backward compatible - All existing configurations continue to work unchanged:

• Static URL configurations work as before
• Default fallbacks ensure server starts without ES_URL
• No breaking changes to API or configuration format

Testing

• ✅ All existing tests pass
• ✅ Server starts successfully without ES_URL environment variable
• ✅ Compiles in both debug and release modes
• ✅ Logging verified for startup and dynamic configurations

Documentation Updates

• Client setup guides for Claude Desktop, Cursor, and Gemini
• Kubernetes/OpenShift deployment examples with YAML manifests
• Environment variable reference for all options
• Authentication examples for both API Key and Basic auth
• Health probe endpoints documented

Commits

1. Add dynamic URL support via X-Elasticsearch-URL header (e80ed01)

   • Core dynamic URL and authentication functionality
   • Comprehensive client documentation
   • SSE transport documentation

2. Add Kubernetes deployment support with environment variables (6dc2894)

   • ENABLE_SSE environment variable
   • Kubernetes deployment guide and examples
   • Generic documentation for all K8s distributions

Files Changed

 README.md                               | 324 +++++++++++++++++++++++++++++++-
 elastic-mcp.json5                       |   4 +-
 src/cli.rs                              |   2 +-
 src/lib.rs                              |   2 +-
 src/servers/elasticsearch/base_tools.rs |   4 +-
 src/servers/elasticsearch/mod.rs        | 134 ++++++++++---
 6 files changed, 433 insertions(+), 37 deletions(-)

Checklist

• Code compiles without errors
• All tests pass
• Documentation updated
• Backward compatible
• Logging added for observability
• Examples provided for common use cases

AI Assistance

AI-assisted-by: Claude Sonnet 4.5

[cla-checker-service]

❌ Author of the following commits did not sign a Contributor Agreement:
e80ed01, 6dc2894

Please, read and sign the above mentioned agreement if you want to contribute to this project

[dustinblack]

❌ Author of the following commits did not sign a Contributor Agreement: e80ed01, 6dc2894

Please, read and sign the above mentioned agreement if you want to contribute to this project

FWIW I don't think I can legally sign the Contributor Agreement on behalf of my employer, and I'm also not entirely sure that the Agreement is compatible with the Apache 2.0 license of this project.

[JoshMock]

Deprecation warning: This MCP server is deprecated and will only receive critical security updates going forward. It has been superseded by Elastic Agent Builder's MCP endpoint, which is available in Elastic 9.2.0+ and Elasticsearch Serverless projects.