{
  "markdown": "# 🧬 ElasticSense\n\nElasticSense is a Claude Code plugin for Elastic workflows. It uses Elastic Agent Builder as the primary integration path and offers a deprecated `legacy_direct` fallback for environments that cannot expose the Agent Builder MCP endpoint yet.\n\nFor end users, the setup flow stays the same in both modes: install the plugin, fill the Claude `userConfig` prompts, then ask Claude for Elastic investigations in natural language. The mode only changes which backend the plugin starts behind the scenes.\n\n## ⚙️ Modes\n\n### Primary mode: Agent Builder\n\nThis is the recommended path for new installations.\n\n- Connects Claude to the MCP endpoint hosted by Kibana's Agent Builder\n- Authenticates with an Elastic API key sent as `Authorization: ApiKey ...`\n- Uses `mcp-remote` locally and stores the bridge dependency in `${CLAUDE_PLUGIN_DATA}`\n- Does not start a full local MCP server beyond that lightweight bridge\n\n### Compatibility fallback: legacy direct mode\n\nThis mode exists only for older stacks or environments where Agent Builder is not available.\n\n- Uses the deprecated `elastic/mcp-server-elasticsearch` server\n- Starts that MCP server locally through `docker.elastic.co/mcp/elasticsearch`\n- Connects directly to Elasticsearch with `ES_URL`, and optionally `ES_API_KEY`\n- Requires Docker on the local machine\n\nElastic has deprecated this MCP server and recommends Agent Builder instead:\n\n- https://github.com/elastic/mcp-server-elasticsearch\n- https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/mcp-server\n\n## 📋 Prerequisites\n\n- Claude Code with plugin support\n- Node.js 18 or newer\n- For Agent Builder mode:\n  - an Elastic deployment with Agent Builder enabled\n  - an API key with `feature_agentBuilder.read`, `read`, `view_index_metadata`, and `monitor_inference`\n- For legacy direct mode:\n  - a reachable Elasticsearch cluster\n  - Docker available locally\n  - optionally an Elasticsearch API key with read-only access to the target indices\n\nReference docs:\n\n- Anthropic plugins: https://code.claude.com/docs/fr/plugins\n- Anthropic marketplaces: https://code.claude.com/docs/fr/plugin-marketplaces\n- Anthropic plugin reference: https://code.claude.com/docs/fr/plugins-reference\n- Elastic Agent Builder MCP server: https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/mcp-server\n- Elastic Agent Builder permissions: https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/permissions\n- Deprecated Elasticsearch MCP server: https://github.com/elastic/mcp-server-elasticsearch\n\n## 🛠 Installation\n\n### Local validation\n\n```bash\nnpm run validate\nnpm run test:smoke\n```\n\n### Marketplace test\n\n```bash\nnpm run validate\nclaude plugin marketplace add ./\nclaude plugin install elastic-sense@elastic-sense-marketplace --scope local\n```\n\nFor development-only loading without installation:\n\n```bash\nclaude --plugin-dir .\n```\n\nClaude asks for:\n\n- `use_legacy_direct_mode`\n- `elastic_mcp_url`\n- `elastic_api_key`\n- `legacy_es_url`\n- `legacy_es_ssl_skip_verify`\n\nFor new installations:\n\n- set `use_legacy_direct_mode` to `false`\n- fill `elastic_mcp_url`\n- fill `elastic_api_key`\n- ignore legacy fields\n\nFor compatibility mode:\n\n- set `use_legacy_direct_mode` to `true`\n- fill `legacy_es_url`\n- fill `elastic_api_key` only if your cluster requires it\n- optionally enable `legacy_es_ssl_skip_verify`\n- ignore `elastic_mcp_url`\n\n## 👤 User setup flow\n\n### Agent Builder flow\n\n1. In Kibana, open Agent Builder and copy the MCP URL.\n2. Create an API key with the documented Kibana + index privileges.\n3. Install and enable the plugin in Claude Code.\n4. Set `use_legacy_direct_mode=false`.\n5. Paste the MCP URL and API key when Claude asks for `userConfig`.\n\n### Legacy direct flow\n\n1. Confirm Agent Builder is not available and that you are intentionally using a deprecated fallback.\n2. Create a read-only Elasticsearch API key.\n3. Ensure Docker is installed locally.\n4. Install and enable the plugin in Claude Code.\n5. Set `use_legacy_direct_mode=true`.\n6. Paste the direct Elasticsearch URL.\n7. Paste an API key only if your cluster requires one.\n\n## 🎯 Use Cases\n\nElasticSense is most useful when Claude needs to turn raw Elastic data into a short investigation workflow rather than a single low-level query.\n\n### 1. Cluster health overview\n\nUse this when you want a quick operational summary of index and shard health.\n\nExample prompt:\n\n```text\nGive me a health overview of the Elasticsearch cluster for k8s-fiaas-app-morpheus-*\n```\n\nTypical output:\n\n- matching indices and their health state\n- yellow or red indices worth investigating first\n- shard allocation clues if available\n- recommended next check\n\n`legacy_direct` note:\nThis works well as long as index and shard data are enough. It will not magically provide rich node-level telemetry.\n\n### 2. Investigate recent errors\n\nUse this when a service is returning errors and you want Claude to isolate the dominant pattern quickly.\n\nExample prompt:\n\n```text\nInvestigate recent errors in logs-* for the payment service during the last hour\n```\n\nTypical output:\n\n- main error messages or status codes\n- first and last occurrence in the requested window\n- affected services or environments when fields are present\n- likely next step for deeper investigation\n\n`legacy_direct` note:\nThis is strongest when your logs are already well structured and searchable.\n\n### 3. Analyze logs for a service\n\nUse this for broad exploration before going into a specific incident or root-cause analysis.\n\nExample prompt:\n\n```text\nAnalyze logs for checkout-service from today and summarize the main issues\n```\n\nTypical output:\n\n- dominant patterns in the selected time range\n- notable spikes or transitions\n- representative log examples\n- suggested drill-down query\n\n`legacy_direct` note:\nPrefer simple ES|QL summaries and targeted searches. Advanced correlation remains limited.\n\n### 4. Check index or shard issues\n\nUse this when an index is unhealthy, slow, or suspected to be misconfigured.\n\nExample prompt:\n\n```text\nCheck shard information for k8s-fiaas-app-morpheus-001789 and explain why it is yellow\n```\n\nTypical output:\n\n- shard layout and health clues\n- whether the issue looks like allocation, replication, or data-layout related\n- immediate operational next steps\n\n`legacy_direct` note:\nThis is one of the strongest fallback scenarios because the deprecated MCP server exposes shard and index tools directly.\n\n## 👥 Perfect For\n\n### SRE and platform teams\n\n- triaging index and shard health issues\n- exploring recent log anomalies\n- validating whether a problem needs deeper Elastic investigation\n\n### Application teams\n\n- checking service-specific logs without writing DSL from scratch\n- getting a first-pass explanation of recent errors\n- narrowing investigation scope before involving Elastic specialists\n\n### Non-expert users with Agent Builder access\n\n- turning Elastic data into guided investigation steps\n- getting concise summaries instead of raw query output\n- using Claude as a front door to common observability questions\n\nThis audience fit is much weaker in `legacy_direct` mode, which remains a technical compatibility fallback.\n\n## 🧰 Helper commands\n\nAgent Builder:\n\n```bash\nnode scripts/auth-setup.js build-url https://kibana.example.com default\nnode scripts/auth-setup.js print-role default \"logs-*,metrics-*\"\nnode scripts/auth-setup.js doctor https://kibana.example.com/api/agent_builder/mcp\n```\n\nLegacy direct:\n\n```bash\nnode scripts/auth-setup.js print-legacy-role \"logs-*,metrics-*\"\nnode scripts/auth-setup.js doctor-legacy https://elasticsearch.example.com:9200\n```\n\n## 🧠 Skills and capability gaps\n\n- `log-analysis`\n- `error-investigation`\n- `performance-monitoring`\n- `cluster-health`\n\nThese skills remain more effective in Agent Builder mode. In `legacy_direct` mode, the available tool surface is smaller because the deprecated Elasticsearch MCP server mainly exposes low-level tools such as `list_indices`, `get_mappings`, `search`, `esql`, and `get_shards`.\n\nThat means:\n\n- Agent Builder mode is the recommended experience\n- legacy direct mode is a compatibility fallback\n- some workflow outputs may become more advisory than executable in legacy mode\n\n## 📦 Bundling model\n\nAnthropic marketplace plugins are copied into Claude's cache, so they cannot rely on files outside the plugin root. ElasticSense uses two runtime paths:\n\n- Agent Builder mode:\n  - plugin metadata in `.claude-plugin/plugin.json`\n  - MCP definition in `config/mcp.json`\n  - `scripts/start-mcp.js` bootstraps `mcp-remote` into `${CLAUDE_PLUGIN_DATA}`\n- legacy direct mode:\n  - `scripts/start-mcp.js` starts the deprecated Docker image `docker.elastic.co/mcp/elasticsearch`\n  - no separate MCP bridge install is required, but Docker must be available\n\n## ✅ Verification\n\nRun:\n\n```bash\nnpm run validate\nnpm run test:smoke\n```\n\n`validate` checks manifests and required files. `test:smoke` validates both runtime branches locally:\n\n- Agent Builder mode with a fake `mcp-remote`\n- legacy direct mode with a fake `docker` executable\n\nIf you update an already installed local plugin, run:\n\n```bash\nclaude plugin update elastic-sense@elastic-sense-marketplace --scope local\n```\n\nThen restart Claude Code so the new version is applied.\n",
  "bytes": 9229,
  "sha": "c111de0da9f82ec2b54f2b0029e8d87268c58639ebfebc60deec7e57f6674cb8",
  "repo_slug": "ahmidbbc/elastic-sense",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ahmidbbc_elastic_sense_elastic_sense_00640982/readme"
}