From 639be80a1b3a683bbb08d04ef00c3ed69ca2f5df Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 20:34:29 +0000 Subject: [PATCH 1/8] Restructure MCP servers docs for clarity - Remove redundant Configuration Structure section - Add 3 tabs (CLI, Holmes Helm, Robusta Helm) throughout - Inline Supergateway into Stdio Helm tabs - Move Dynamic Headers to Advanced Configuration section - Remove Configuration Fields list (examples are self-documenting) - Remove Default Mode section - Use bold text instead of subheaders within tabs https://claude.ai/code/session_01H3xyWcwWem2ptcZjFaNs8n Signed-off-by: Claude --- docs/data-sources/remote-mcp-servers.md | 556 +++++++++--------------- 1 file changed, 203 insertions(+), 353 deletions(-) diff --git a/docs/data-sources/remote-mcp-servers.md b/docs/data-sources/remote-mcp-servers.md index c0bf297fbe..7e44286d51 100644 --- a/docs/data-sources/remote-mcp-servers.md +++ b/docs/data-sources/remote-mcp-servers.md @@ -1,201 +1,152 @@ # MCP Servers -HolmesGPT can integrate with MCP (Model Context Protocol) servers to access external data sources and tools in real time. This guide provides step-by-step instructions for configuring HolmesGPT to connect with MCP servers. +HolmesGPT can integrate with MCP (Model Context Protocol) servers to access external data sources and tools in real time. ## Transport Modes HolmesGPT supports three MCP transport modes: -1. **`streamable-http`** (Recommended): Modern transport mode that uses HTTP POST requests with JSON responses. This is the preferred mode for new integrations. -2. **`stdio`**: Direct process communication using standard input/output. Recommended for **Holmes CLI** usage only. For in-cluster deployments, see the [workaround using Supergateway](#working-with-stdio-mcp-servers-via-supergateway). -3. **`sse`** (Deprecated): Legacy transport mode using Server-Sent Events. Maintained for backward compatibility only. We strongly recommend using `streamable-http` mode for new integrations. - -## Configuration Structure - -**`mcp_servers` is a separate top-level key** in the configuration file, alongside `toolsets`. Both can coexist in the same config file: - -```yaml -toolsets: - my_custom_toolset: - # ... toolset configuration - -mcp_servers: - my_mcp_server: - # ... MCP server configuration -``` - -Internally, MCP servers are treated as toolsets with `type: MCP` and are merged with other toolsets. This means MCP servers appear alongside regular toolsets in HolmesGPT's toolset list and can be enabled/disabled like any other toolset. +1. **`streamable-http`** (Recommended): Modern HTTP-based transport. Use this for new integrations. +2. **`stdio`**: Direct process communication via standard input/output. For CLI usage; Kubernetes deployments require Supergateway. +3. **`sse`** (Deprecated): Legacy Server-Sent Events transport. Use `streamable-http` instead. ## Streamable-HTTP (Recommended) -Streamable-HTTP is the recommended transport mode for all new MCP server integrations. It uses HTTP POST requests with JSON responses and provides better compatibility and future-proofing. - -### Configuration - -The transport mode and URL are specified in the `config` section of your MCP server configuration: - -```yaml -mcp_servers: - my_server: - description: "My MCP server" - config: - url: "http://example.com:8000/mcp/messages" # Path depends on your server - mode: streamable-http # Explicitly set the mode - headers: - Authorization: "Bearer token123" - llm_instructions: "This server provides general data access capabilities. Use it when you need to retrieve external information or perform remote operations that aren't covered by other toolsets." -``` - -#### Dynamic Headers with Request Context - -MCP servers can use dynamic headers that are populated from the incoming HTTP request context. This is useful for passing authentication tokens or other request-specific headers to your MCP server. - -Use the `extra_headers` field (instead of `headers`) with template variables to reference headers from the incoming request: +=== "Holmes CLI" -```yaml -mcp_servers: - my_server: - description: "My MCP server with dynamic authentication" - config: - url: "http://example.com:8000/mcp/messages" - mode: streamable-http - extra_headers: - X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" - X-User-Id: "{{ request_context.headers['X-User-Id'] }}" - llm_instructions: "Use this server to access resources with per-request authentication." -``` + Create a config file and pass it when running CLI commands. -**How it works:** + **custom_toolset.yaml:** -- When a request comes to HolmesGPT (via the server API), headers from that request are available in `request_context.headers` -- Header lookups are case-insensitive (e.g., `X-Auth-Token`, `x-auth-token`, and `X-AUTH-TOKEN` all work) -- The template is rendered when calling the MCP server, passing the header value through -- You can also use environment variables: `"{{ env.MY_VAR }}"` or combine them: `"Bearer {{ request_context.headers['token'] }}"` + ```yaml + mcp_servers: + my_server: + description: "My MCP server" + config: + url: "http://example.com:8000/mcp/messages" + mode: streamable-http + headers: + Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" + llm_instructions: "Use this server to access external data and perform remote operations." + ``` -**Example use case:** + ```bash + holmes ask -t custom_toolset.yaml "Query my MCP server" + ``` -This is particularly useful when your MCP server needs to authenticate with external services using tokens that are specific to each request/user. + Alternatively, add the config to `~/.holmes/config.yaml` and run without `-t`. -```yaml -mcp_servers: - remote_api_server: - description: "Remote API MCP Server" - config: - url: "http://mcp-server:8000/mcp" - mode: streamable-http - extra_headers: - X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" - llm_instructions: "Use this server to interact with remote APIs." -``` +=== "Holmes Helm Chart" -When making requests to HolmesGPT, include the required header: + Add to your Helm values: -```bash -curl -X POST http://holmes-server/api/investigate \ - -H "X-Auth-Token: your-auth-token-here" \ - -H "Content-Type: application/json" \ - -d '{"question": "Check system status"}' -``` + ```yaml + holmes: + additionalEnvVars: + - name: MY_MCP_API_KEY + valueFrom: + secretKeyRef: + name: mcp-credentials + key: api_key + + custom_toolsets: + mcp_servers: + my_server: + description: "My MCP server" + config: + url: "http://example.com:8000/mcp/messages" + mode: streamable-http + headers: + Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" + llm_instructions: "Use this server to access external data and perform remote operations." + ``` -### URL Format + ```bash + helm upgrade holmes robusta/holmes --values=values.yaml + ``` -The URL should point to the MCP server endpoint. The exact path depends on your server configuration: +=== "Robusta Helm Chart" -- Some servers use `/mcp/messages` (e.g., `http://example.com:8000/mcp/messages`) -- Others use `/mcp` (e.g., `http://example.com:3333/mcp`) -- Custom paths as defined by your server + Add to your `generated_values.yaml`: -The streamable-http client automatically handles POST requests and responses at the provided URL. Consult your MCP server's documentation to determine the correct endpoint path. + ```yaml + holmes: + additionalEnvVars: + - name: MY_MCP_API_KEY + valueFrom: + secretKeyRef: + name: mcp-credentials + key: api_key + + custom_toolsets: + mcp_servers: + my_server: + description: "My MCP server" + config: + url: "http://example.com:8000/mcp/messages" + mode: streamable-http + headers: + Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" + llm_instructions: "Use this server to access external data and perform remote operations." + ``` -### Example Configuration + ```bash + helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= + ``` -```yaml-helm-values -mcp_servers: - mcp_server_1: - description: "Remote mcp server using streamable-http" - config: - url: "http://example.com:8000/mcp/messages" # Path may vary: /mcp, /mcp/messages, or custom path - mode: streamable-http # Explicitly set the preferred mode - headers: - Authorization: "Bearer {{ env.my_mcp_server_key }}" # You can use holmes environment variables as headers - llm_instructions: "This server provides general data access capabilities. Use it when you need to retrieve external information or perform remote operations that aren't covered by other toolsets." -``` +The URL path depends on your MCP server (e.g., `/mcp/messages`, `/mcp`, or a custom path). Check your server's documentation. ## Stdio -Stdio mode allows HolmesGPT to run MCP servers directly as subprocesses, communicating via standard input/output. - -**Important:** Stdio mode is **recommended for Holmes CLI usage only**. For in-cluster deployments (Helm charts), stdio mode has limitations due to the Holmes container image. If you need to use stdio-based MCP servers in-cluster, see the [workaround using Supergateway](#working-with-stdio-mcp-servers-via-supergateway). - -### Configuration Fields - -- `mode`: Must be set to `stdio` -- `command`: The command to execute (e.g., `python3`, `node`, `/usr/bin/my-mcp-server`) -- `args`: (Optional) List of arguments to pass to the command -- `env`: (Optional) Dictionary of environment variables to set for the process - -### Configuration Examples +Stdio mode runs MCP servers as subprocesses, communicating via standard input/output. === "Holmes CLI" - Use a config file, and pass it when running CLI commands. + Create a config file and pass it when running CLI commands. **custom_toolset.yaml:** ```yaml mcp_servers: - stdio_example: - description: "Custom stdio MCP server running as a subprocess" + my_stdio_server: + description: "Custom stdio MCP server" config: mode: stdio command: "python3" args: - - "./stdio_server.py" + - "./my_mcp_server.py" env: CUSTOM_VAR: "value" - llm_instructions: "Use this MCP server to access custom tools and capabilities provided by the stdio server process. Refer to the available tools from this server when needed." + llm_instructions: "Use this server to access custom tools provided by the stdio server." ``` - **Note:** Ensure that the required Python packages (like `mcp` and `fastmcp`) are installed in your Python environment. - - You can now use Holmes via the CLI with your configured stdio MCP server. For example: - ```bash - holmes ask -t custom_toolset.yaml "Run my mcp-server tools" + holmes ask -t custom_toolset.yaml "Run my MCP server tools" ``` -=== "Holmes Helm Chart" - - !!! warning "Stdio Limitations in Helm Deployments" - **Stdio mode is not recommended for running MCP servers directly in the Holmes container** due to limitations of the Holmes container image. Your stdio MCP server may have dependencies (Python packages, system libraries, etc.) that are not available in the Holmes image, which will cause the server to fail. + Ensure required dependencies (e.g., `mcp`, `fastmcp` packages) are installed in your environment. - **Recommended Approach: Run stdio MCP servers as an HTTP MCP server pod** +=== "Holmes Helm Chart" - For in-cluster deployments, run your stdio MCP server in its own container using Supergateway to convert it to HTTP, then connect Holmes to it. + !!! warning "Stdio requires Supergateway for Kubernetes" + Stdio mode cannot run directly in the Holmes container due to missing dependencies. Run your stdio MCP server in a separate pod using [Supergateway](https://github.com/supercorp-ai/supergateway) to expose it as HTTP. - **First, create a custom Docker image** that contains your stdio MCP server and all its required dependencies. Use the Supergateway base image pattern: + **Create a Docker image with your MCP server:** ```dockerfile FROM supercorp/supergateway:latest USER root - # Add needed files and dependencies here + # Install your MCP server dependencies # Example: RUN apk add --no-cache python3 py3-pip - # Example: RUN pip3 install --no-cache-dir --break-system-packages your-mcp-server-package + # Example: RUN pip3 install --no-cache-dir --break-system-packages your-mcp-package USER node EXPOSE 8000 - # Replace "YOUR MCP SERVER COMMAND HERE" with your actual MCP server command - # Examples: - # CMD ["--port", "8000", "--stdio", "python3", "-m", "your_mcp_server_module"] - # CMD ["--port", "8000", "--stdio", "python3", "/app/stdio_server.py"] - # CMD ["--port", "8000", "--stdio", "npx", "-y", "@your-org/your-mcp-server@latest"] - CMD ["--port", "8000", "--stdio", "YOUR MCP SERVER COMMAND HERE"] + CMD ["--port", "8000", "--stdio", "python3", "-m", "your_mcp_module"] ``` - Build and push your image. - - **Deploy the MCP server in your cluster:** + **Deploy the MCP server pod:** ```yaml apiVersion: v1 @@ -210,15 +161,12 @@ Stdio mode allows HolmesGPT to run MCP servers directly as subprocesses, communi image: your-registry/your-mcp-server:latest ports: - containerPort: 8000 - args: - - "--stdio" - # Replace "YOUR MCP SERVER COMMAND HERE" with your actual MCP server command - # Examples: "python3 -m your_mcp_server_module", "python3 /app/stdio_server.py", "npx -y @your-org/your-mcp-server@latest" - - "YOUR MCP SERVER COMMAND HERE" - - "--port" - - "8000" - - "--logLevel" - - "debug" + env: + - name: API_KEY + valueFrom: + secretKeyRef: + name: mcp-credentials + key: api_key stdin: true tty: true --- @@ -238,56 +186,43 @@ Stdio mode allows HolmesGPT to run MCP servers directly as subprocesses, communi **Connect Holmes to the MCP server:** - After deploying the MCP server, configure Holmes to connect to it via HTTP: - ```yaml - mcp_servers: - my_mcp_server: - description: "My custom MCP server running in-cluster" - config: - url: "http://my-mcp-server.default.svc.cluster.local:8000/mcp/messages" # Use streamable-http endpoint - mode: streamable-http # Or sse if Supergateway doesn't support streamable-http yet - llm_instructions: "Use this MCP server to access custom tools and capabilities. Refer to the available tools from this server when needed." + holmes: + custom_toolsets: + mcp_servers: + my_mcp_server: + description: "My stdio MCP server via Supergateway" + config: + url: "http://my-mcp-server.default.svc.cluster.local:8000/sse" + mode: sse + llm_instructions: "Use this server to access custom tools." ``` - Apply the configuration: - ```bash - helm upgrade holmes holmes/holmes --values=values.yaml + helm upgrade holmes robusta/holmes --values=values.yaml ``` === "Robusta Helm Chart" - !!! warning "Stdio Limitations in Helm Deployments" - **Stdio mode is not recommended for running MCP servers directly in the Holmes container** due to limitations of the Holmes container image. Your stdio MCP server may have dependencies (Python packages, system libraries, etc.) that are not available in the Holmes image, which will cause the server to fail. + !!! warning "Stdio requires Supergateway for Kubernetes" + Stdio mode cannot run directly in the Holmes container due to missing dependencies. Run your stdio MCP server in a separate pod using [Supergateway](https://github.com/supercorp-ai/supergateway) to expose it as HTTP. - **Recommended Approach: Run stdio MCP servers as an HTTP MCP server pod** - - For in-cluster deployments, run your stdio MCP server in its own container using Supergateway to convert it to HTTP, then connect Holmes to it. - - **First, create a custom Docker image** that contains your stdio MCP server and all its required dependencies. Use the Supergateway base image pattern: + **Create a Docker image with your MCP server:** ```dockerfile FROM supercorp/supergateway:latest USER root - # Add needed files and dependencies here + # Install your MCP server dependencies # Example: RUN apk add --no-cache python3 py3-pip - # Example: RUN pip3 install --no-cache-dir --break-system-packages your-mcp-server-package + # Example: RUN pip3 install --no-cache-dir --break-system-packages your-mcp-package USER node EXPOSE 8000 - # Replace "YOUR MCP SERVER COMMAND HERE" with your actual MCP server command - # Examples: - # CMD ["--port", "8000", "--stdio", "python3", "-m", "your_mcp_server_module"] - # CMD ["--port", "8000", "--stdio", "python3", "/app/stdio_server.py"] - # CMD ["--port", "8000", "--stdio", "npx", "-y", "@your-org/your-mcp-server@latest"] - CMD ["--port", "8000", "--stdio", "YOUR MCP SERVER COMMAND HERE"] + CMD ["--port", "8000", "--stdio", "python3", "-m", "your_mcp_module"] ``` - Build and push your image. - - **Deploy the MCP server in your cluster:** + **Deploy the MCP server pod:** ```yaml apiVersion: v1 @@ -302,15 +237,12 @@ Stdio mode allows HolmesGPT to run MCP servers directly as subprocesses, communi image: your-registry/your-mcp-server:latest ports: - containerPort: 8000 - args: - - "--stdio" - # Replace "YOUR MCP SERVER COMMAND HERE" with your actual MCP server command - # Examples: "python3 -m your_mcp_server_module", "python3 /app/stdio_server.py", "npx -y @your-org/your-mcp-server@latest" - - "YOUR MCP SERVER COMMAND HERE" - - "--port" - - "8000" - - "--logLevel" - - "debug" + env: + - name: API_KEY + valueFrom: + secretKeyRef: + name: mcp-credentials + key: api_key stdin: true tty: true --- @@ -330,208 +262,127 @@ Stdio mode allows HolmesGPT to run MCP servers directly as subprocesses, communi **Connect Holmes to the MCP server:** - After deploying the MCP server, configure Holmes to connect to it via HTTP: - ```yaml - mcp_servers: - my_mcp_server: - description: "My custom MCP server running in-cluster" - config: - url: "http://my-mcp-server.default.svc.cluster.local:8000/mcp/messages" # Use streamable-http endpoint - mode: streamable-http # Or sse if Supergateway doesn't support streamable-http yet - llm_instructions: "Use this MCP server to access custom tools and capabilities. Refer to the available tools from this server when needed." + holmes: + custom_toolsets: + mcp_servers: + my_mcp_server: + description: "My stdio MCP server via Supergateway" + config: + url: "http://my-mcp-server.default.svc.cluster.local:8000/sse" + mode: sse + llm_instructions: "Use this server to access custom tools." ``` - Apply the configuration: - ```bash helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= ``` ## SSE (Deprecated) -SSE (Server-Sent Events) transport mode is deprecated across the MCP ecosystem. We strongly recommend using `streamable-http` mode for new integrations. SSE mode support is maintained for backward compatibility but may be removed in future versions. - -### Configuration - -```yaml-helm-values -mcp_servers: - mcp_server_legacy: - description: "Legacy MCP server using SSE (deprecated)" - config: - url: "http://example.com:8000/sse" # Must end with /sse - mode: sse # Explicitly set, though this is deprecated - llm_instructions: "Legacy server using deprecated SSE transport." -``` - -### URL Format - -URL should end with `/sse` (e.g., `http://example.com:8000/sse`). If the URL doesn't end with `/sse`, HolmesGPT will automatically append it. - -## Working with Stdio MCP Servers via Supergateway - -For in-cluster deployments, if you need to use stdio-based MCP servers, you can run them in their own container using Supergateway to convert them to HTTP endpoints, then connect Holmes to them. - -!!! tip "Prefer Streamable-HTTP" - When using Supergateway or similar tools, configure them to use `streamable-http` mode instead of SSE for better compatibility and future-proofing. - -While HolmesGPT now supports **stdio** mode directly, you may still want to use Supergateway in some scenarios: -- When you need to expose a stdio-based MCP server as an HTTP endpoint for multiple clients -- When you want to run the MCP server in a separate pod/container for better isolation -- When integrating with existing stdio-based MCP servers that you prefer to keep separate - -Tools like Supergateway can act as a bridge by converting stdio-based MCPs into streamable-http or SSE-compatible endpoints. - -For this demo we will use: -- [Dynatrace MCP](https://github.com/dynatrace-oss/dynatrace-mcp) -- [Supergateway](https://github.com/supercorp-ai/supergateway) - runs MCP stdio-based servers over HTTP - -Check out supergateway docs to find out other useful flags. - -**See it in action** +SSE transport is deprecated. Use `streamable-http` for new integrations. -
- -### 1. Run stdio MCP as HTTP endpoint - -=== "Docker" - - This command runs the Dynatrace MCP server locally via Docker using Supergateway to wrap it with HTTP support. - Credentials (e.g., API keys) should be stored in a .env file passed to Docker using --env-file. - You can change `"npx -y @dynatrace-oss/dynatrace-mcp-server@latest /"` to your specific MCP. +=== "Holmes CLI" - ```shell - docker run --env-file .env -it --rm -p 8003:8003 supercorp/supergateway \ - --stdio "npx -y @dynatrace-oss/dynatrace-mcp-server@latest /" \ - --port 8003 \ - --logLevel debug + ```yaml + mcp_servers: + legacy_server: + description: "Legacy MCP server using SSE" + config: + url: "http://example.com:8000/sse" + mode: sse + llm_instructions: "Legacy server." ``` - Once the container starts, you should see logs similar to: - - ```shell - [supergateway] Starting... - [supergateway] Supergateway is supported by Supermachine (hosted MCPs) - https://supermachine.ai - [supergateway] - outputTransport: sse - [supergateway] - Headers: (none) - [supergateway] - port: 8003 - [supergateway] - stdio: npx -y @dynatrace-oss/dynatrace-mcp-server@latest / - [supergateway] - ssePath: /sse - [supergateway] - messagePath: /message - [supergateway] - CORS: disabled - [supergateway] - Health endpoints: (none) - [supergateway] Listening on port 8003 - [supergateway] SSE endpoint: http://localhost:8003/sse - [supergateway] POST messages: http://localhost:8003/message - ``` +=== "Holmes Helm Chart" -=== "Kubernetes Pod" + ```yaml + holmes: + custom_toolsets: + mcp_servers: + legacy_server: + description: "Legacy MCP server using SSE" + config: + url: "http://example.com:8000/sse" + mode: sse + llm_instructions: "Legacy server." + ``` - This will run dynatrace MCP server as a pod in your cluster. - Credentials are passed as env vars. +=== "Robusta Helm Chart" ```yaml - apiVersion: v1 - kind: Pod - metadata: - name: dynatrace-mcp - labels: - app: dynatrace-mcp - spec: - containers: - - name: supergateway - image: supercorp/supergateway - env: - - name: DT_ENVIRONMENT - value: https://abcd1234.apps.dynatrace.com - - name: OAUTH_CLIENT_ID - value: dt0s02.SAMPLE - - name: OAUTH_CLIENT_SECRET - valueFrom: - secretKeyRef: - name: dynatrace-credentials - key: client_secret - ports: - - containerPort: 8003 - args: - - "--stdio" - - "npx -y @dynatrace-oss/dynatrace-mcp-server@latest /" - - "--port" - - "8003" - - "--logLevel" - - "debug" - stdin: true - tty: true - --- - apiVersion: v1 - kind: Service - metadata: - name: dynatrace-mcp - spec: - selector: - app: dynatrace-mcp - ports: - - protocol: TCP - port: 8003 - targetPort: 8003 - type: ClusterIP + holmes: + custom_toolsets: + mcp_servers: + legacy_server: + description: "Legacy MCP server using SSE" + config: + url: "http://example.com:8000/sse" + mode: sse + llm_instructions: "Legacy server." ``` -### 2. Add MCP server to holmes config +The URL should end with `/sse`. If it doesn't, HolmesGPT will automatically append it. + +## Advanced Configuration -With the MCP server running, configure HolmesGPT to connect to it. +**Dynamic Headers with Request Context** -**Configuration:** +MCP servers can use dynamic headers populated from the incoming HTTP request. This is useful for passing per-request authentication tokens. === "Holmes CLI" - Use a config file, and pass it when running CLI commands. + Not applicable - request context is only available when running Holmes as a server. - **custom_toolset.yaml:** +=== "Holmes Helm Chart" ```yaml - mcp_servers: - mcp_server_1: - description: "Dynatrace observability platform. Bring real-time observability data directly into your development workflow." - config: - url: "http://localhost:8003/sse" - mode: sse # Or use streamable-http if Supergateway supports it - llm_instructions: "Use Dynatrace to analyze application performance, infrastructure monitoring, and real-time observability data. Query metrics, traces, and logs to identify performance bottlenecks, errors, and system health issues in your applications and infrastructure." + holmes: + custom_toolsets: + mcp_servers: + my_server: + description: "MCP server with dynamic auth" + config: + url: "http://mcp-server:8000/mcp" + mode: streamable-http + extra_headers: + X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" + llm_instructions: "Use this server with per-request authentication." ``` - You can now use Holmes via the CLI with your configured MCP server. For example: - - ```bash - holmes ask -t custom_toolset.yaml "Using dynatrace what issues do I have in my cluster?" - ``` - - Alternatively, you can add the `mcp_servers` configurations to ** ~/.holmes/config.yaml**, and run: +=== "Robusta Helm Chart" - ```bash - holmes ask "Using dynatrace what issues do I have in my cluster?" + ```yaml + holmes: + custom_toolsets: + mcp_servers: + my_server: + description: "MCP server with dynamic auth" + config: + url: "http://mcp-server:8000/mcp" + mode: streamable-http + extra_headers: + X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" + llm_instructions: "Use this server with per-request authentication." ``` -=== "Helm Chart" - - ```yaml-helm-values - mcp_servers: - mcp_server_1: - description: "Dynatrace observability platform. Bring real-time observability data directly into your development workflow." - config: - url: "http://dynatrace-mcp.default.svc.cluster.local:8003/sse" - mode: sse # Or use streamable-http if Supergateway supports it - llm_instructions: "Use Dynatrace to analyze application performance, infrastructure monitoring, and real-time observability data. Query metrics, traces, and logs to identify performance bottlenecks, errors, and system health issues in your applications and infrastructure." - ``` +When making requests to HolmesGPT, include the required header: -After the deployment is complete, you can use HolmesGPT and ask questions like *Using dynatrace what issues do I have in my cluster?*. +```bash +curl -X POST http://holmes-server/api/investigate \ + -H "X-Auth-Token: your-auth-token-here" \ + -H "Content-Type: application/json" \ + -d '{"question": "Check system status"}' +``` -## Compatibility and Deprecation Notes +Header lookups are case-insensitive. You can also use environment variables (`{{ env.MY_VAR }}`) or combine them (`Bearer {{ request_context.headers['token'] }}`). -### Configuration Format Change +## Configuration Format Migration -**The MCP server configuration format has been updated.** The `url` field must now be specified inside the `config` section instead of at the top level. The old format (with `url` at the top level) is still supported for backward compatibility but will log a migration warning. Please update your configurations to use the new format. +The MCP server configuration format has been updated. The `url` field must now be inside the `config` section. **Old format (deprecated):** + ```yaml mcp_servers: my_server: @@ -540,6 +391,7 @@ mcp_servers: ``` **New format:** + ```yaml mcp_servers: my_server: @@ -549,6 +401,4 @@ mcp_servers: mode: streamable-http ``` -### Default Mode - -If no mode is specified, the system defaults to `sse` for backward compatibility. However, **this default will be deprecated in the future**, and **you should explicitly set `mode: streamable-http` or `mode: sse`** for new and old servers. +The old format still works but will log a migration warning. From de3385d8747f1444206b0aff10bf5d2a2f3288bd Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 20:36:56 +0000 Subject: [PATCH 2/8] Clarify stdio transport mode description https://claude.ai/code/session_01H3xyWcwWem2ptcZjFaNs8n Signed-off-by: Claude --- docs/data-sources/remote-mcp-servers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data-sources/remote-mcp-servers.md b/docs/data-sources/remote-mcp-servers.md index 7e44286d51..7bce9d1fab 100644 --- a/docs/data-sources/remote-mcp-servers.md +++ b/docs/data-sources/remote-mcp-servers.md @@ -7,7 +7,7 @@ HolmesGPT can integrate with MCP (Model Context Protocol) servers to access exte HolmesGPT supports three MCP transport modes: 1. **`streamable-http`** (Recommended): Modern HTTP-based transport. Use this for new integrations. -2. **`stdio`**: Direct process communication via standard input/output. For CLI usage; Kubernetes deployments require Supergateway. +2. **`stdio`**: Direct process communication via standard input/output. Supported directly in CLI; supported on Kubernetes via [Supergateway](https://github.com/supercorp-ai/supergateway). 3. **`sse`** (Deprecated): Legacy Server-Sent Events transport. Use `streamable-http` instead. ## Streamable-HTTP (Recommended) From f4c40d1ea6341f0dd38e490dff6bfc2414b63a0e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 20:52:32 +0000 Subject: [PATCH 3/8] Add CMD examples to Dockerfile in MCP docs https://claude.ai/code/session_01H3xyWcwWem2ptcZjFaNs8n Signed-off-by: Claude --- docs/data-sources/remote-mcp-servers.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/data-sources/remote-mcp-servers.md b/docs/data-sources/remote-mcp-servers.md index 7bce9d1fab..c0c7f60e14 100644 --- a/docs/data-sources/remote-mcp-servers.md +++ b/docs/data-sources/remote-mcp-servers.md @@ -143,6 +143,10 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou USER node EXPOSE 8000 + # Replace with your MCP server command. Examples: + # CMD ["--port", "8000", "--stdio", "python3", "-m", "your_mcp_module"] + # CMD ["--port", "8000", "--stdio", "python3", "/app/stdio_server.py"] + # CMD ["--port", "8000", "--stdio", "npx", "-y", "@your-org/your-mcp-server@latest"] CMD ["--port", "8000", "--stdio", "python3", "-m", "your_mcp_module"] ``` @@ -219,6 +223,10 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou USER node EXPOSE 8000 + # Replace with your MCP server command. Examples: + # CMD ["--port", "8000", "--stdio", "python3", "-m", "your_mcp_module"] + # CMD ["--port", "8000", "--stdio", "python3", "/app/stdio_server.py"] + # CMD ["--port", "8000", "--stdio", "npx", "-y", "@your-org/your-mcp-server@latest"] CMD ["--port", "8000", "--stdio", "python3", "-m", "your_mcp_module"] ``` From ce88ea8d62b4d4f87966b2ac732eb0cccbc5f65d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 20:53:13 +0000 Subject: [PATCH 4/8] Add args with examples to Pod YAML in MCP docs Allows users to override the MCP server command at deploy time without rebuilding the Docker image. https://claude.ai/code/session_01H3xyWcwWem2ptcZjFaNs8n Signed-off-by: Claude --- docs/data-sources/remote-mcp-servers.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/data-sources/remote-mcp-servers.md b/docs/data-sources/remote-mcp-servers.md index c0c7f60e14..1239f7e437 100644 --- a/docs/data-sources/remote-mcp-servers.md +++ b/docs/data-sources/remote-mcp-servers.md @@ -165,6 +165,15 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou image: your-registry/your-mcp-server:latest ports: - containerPort: 8000 + args: + - "--stdio" + # Replace with your MCP server command + # Examples: "python3 -m your_mcp_module", "python3 /app/stdio_server.py", "npx -y @your-org/your-mcp-server@latest" + - "python3 -m your_mcp_module" + - "--port" + - "8000" + - "--logLevel" + - "debug" env: - name: API_KEY valueFrom: @@ -245,6 +254,15 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou image: your-registry/your-mcp-server:latest ports: - containerPort: 8000 + args: + - "--stdio" + # Replace with your MCP server command + # Examples: "python3 -m your_mcp_module", "python3 /app/stdio_server.py", "npx -y @your-org/your-mcp-server@latest" + - "python3 -m your_mcp_module" + - "--port" + - "8000" + - "--logLevel" + - "debug" env: - name: API_KEY valueFrom: From a39c0987d51988f8656a854eb9d5d18b4233bfcf Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 20:55:46 +0000 Subject: [PATCH 5/8] Fix Helm values structure for mcp_servers mcp_servers is a top-level key in Helm values, not nested under custom_toolsets. Fixed all Helm chart examples: - Holmes Helm: mcp_servers at root level - Robusta Helm: holmes.mcp_servers (not holmes.custom_toolsets.mcp_servers) https://claude.ai/code/session_01H3xyWcwWem2ptcZjFaNs8n Signed-off-by: Claude --- docs/data-sources/remote-mcp-servers.md | 152 +++++++++++------------- 1 file changed, 70 insertions(+), 82 deletions(-) diff --git a/docs/data-sources/remote-mcp-servers.md b/docs/data-sources/remote-mcp-servers.md index 1239f7e437..6b60f8c7bf 100644 --- a/docs/data-sources/remote-mcp-servers.md +++ b/docs/data-sources/remote-mcp-servers.md @@ -41,24 +41,22 @@ HolmesGPT supports three MCP transport modes: Add to your Helm values: ```yaml - holmes: - additionalEnvVars: - - name: MY_MCP_API_KEY - valueFrom: - secretKeyRef: - name: mcp-credentials - key: api_key + additionalEnvVars: + - name: MY_MCP_API_KEY + valueFrom: + secretKeyRef: + name: mcp-credentials + key: api_key - custom_toolsets: - mcp_servers: - my_server: - description: "My MCP server" - config: - url: "http://example.com:8000/mcp/messages" - mode: streamable-http - headers: - Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" - llm_instructions: "Use this server to access external data and perform remote operations." + mcp_servers: + my_server: + description: "My MCP server" + config: + url: "http://example.com:8000/mcp/messages" + mode: streamable-http + headers: + Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" + llm_instructions: "Use this server to access external data and perform remote operations." ``` ```bash @@ -78,16 +76,15 @@ HolmesGPT supports three MCP transport modes: name: mcp-credentials key: api_key - custom_toolsets: - mcp_servers: - my_server: - description: "My MCP server" - config: - url: "http://example.com:8000/mcp/messages" - mode: streamable-http - headers: - Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" - llm_instructions: "Use this server to access external data and perform remote operations." + mcp_servers: + my_server: + description: "My MCP server" + config: + url: "http://example.com:8000/mcp/messages" + mode: streamable-http + headers: + Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" + llm_instructions: "Use this server to access external data and perform remote operations." ``` ```bash @@ -200,15 +197,13 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou **Connect Holmes to the MCP server:** ```yaml - holmes: - custom_toolsets: - mcp_servers: - my_mcp_server: - description: "My stdio MCP server via Supergateway" - config: - url: "http://my-mcp-server.default.svc.cluster.local:8000/sse" - mode: sse - llm_instructions: "Use this server to access custom tools." + mcp_servers: + my_mcp_server: + description: "My stdio MCP server via Supergateway" + config: + url: "http://my-mcp-server.default.svc.cluster.local:8000/sse" + mode: sse + llm_instructions: "Use this server to access custom tools." ``` ```bash @@ -290,14 +285,13 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou ```yaml holmes: - custom_toolsets: - mcp_servers: - my_mcp_server: - description: "My stdio MCP server via Supergateway" - config: - url: "http://my-mcp-server.default.svc.cluster.local:8000/sse" - mode: sse - llm_instructions: "Use this server to access custom tools." + mcp_servers: + my_mcp_server: + description: "My stdio MCP server via Supergateway" + config: + url: "http://my-mcp-server.default.svc.cluster.local:8000/sse" + mode: sse + llm_instructions: "Use this server to access custom tools." ``` ```bash @@ -323,29 +317,26 @@ SSE transport is deprecated. Use `streamable-http` for new integrations. === "Holmes Helm Chart" ```yaml - holmes: - custom_toolsets: - mcp_servers: - legacy_server: - description: "Legacy MCP server using SSE" - config: - url: "http://example.com:8000/sse" - mode: sse - llm_instructions: "Legacy server." + mcp_servers: + legacy_server: + description: "Legacy MCP server using SSE" + config: + url: "http://example.com:8000/sse" + mode: sse + llm_instructions: "Legacy server." ``` === "Robusta Helm Chart" ```yaml holmes: - custom_toolsets: - mcp_servers: - legacy_server: - description: "Legacy MCP server using SSE" - config: - url: "http://example.com:8000/sse" - mode: sse - llm_instructions: "Legacy server." + mcp_servers: + legacy_server: + description: "Legacy MCP server using SSE" + config: + url: "http://example.com:8000/sse" + mode: sse + llm_instructions: "Legacy server." ``` The URL should end with `/sse`. If it doesn't, HolmesGPT will automatically append it. @@ -363,33 +354,30 @@ MCP servers can use dynamic headers populated from the incoming HTTP request. Th === "Holmes Helm Chart" ```yaml - holmes: - custom_toolsets: - mcp_servers: - my_server: - description: "MCP server with dynamic auth" - config: - url: "http://mcp-server:8000/mcp" - mode: streamable-http - extra_headers: - X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" - llm_instructions: "Use this server with per-request authentication." + mcp_servers: + my_server: + description: "MCP server with dynamic auth" + config: + url: "http://mcp-server:8000/mcp" + mode: streamable-http + extra_headers: + X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" + llm_instructions: "Use this server with per-request authentication." ``` === "Robusta Helm Chart" ```yaml holmes: - custom_toolsets: - mcp_servers: - my_server: - description: "MCP server with dynamic auth" - config: - url: "http://mcp-server:8000/mcp" - mode: streamable-http - extra_headers: - X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" - llm_instructions: "Use this server with per-request authentication." + mcp_servers: + my_server: + description: "MCP server with dynamic auth" + config: + url: "http://mcp-server:8000/mcp" + mode: streamable-http + extra_headers: + X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" + llm_instructions: "Use this server with per-request authentication." ``` When making requests to HolmesGPT, include the required header: From 1084ea973e914caf41ebbfcbd1d72b952d965633 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 21:00:12 +0000 Subject: [PATCH 6/8] Replace generic llm_instructions with realistic examples - Use Dynatrace as example for streamable-http (observability platform) - Use ticket database as example for stdio (internal tool) - Use legacy analytics as example for SSE - Use customer data API for dynamic headers example - Add comment explaining what llm_instructions is for - Update example commands to match the example servers https://claude.ai/code/session_01H3xyWcwWem2ptcZjFaNs8n Signed-off-by: Claude --- docs/data-sources/remote-mcp-servers.md | 102 +++++++++++++----------- 1 file changed, 54 insertions(+), 48 deletions(-) diff --git a/docs/data-sources/remote-mcp-servers.md b/docs/data-sources/remote-mcp-servers.md index 6b60f8c7bf..56eedd883a 100644 --- a/docs/data-sources/remote-mcp-servers.md +++ b/docs/data-sources/remote-mcp-servers.md @@ -20,18 +20,19 @@ HolmesGPT supports three MCP transport modes: ```yaml mcp_servers: - my_server: - description: "My MCP server" + dynatrace: + description: "Dynatrace observability platform" config: - url: "http://example.com:8000/mcp/messages" + url: "http://dynatrace-mcp:8000/mcp/messages" mode: streamable-http headers: - Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" - llm_instructions: "Use this server to access external data and perform remote operations." + Authorization: "Bearer {{ env.DYNATRACE_API_KEY }}" + # llm_instructions tells Holmes WHEN and HOW to use this server + llm_instructions: "Use Dynatrace to investigate application performance issues, analyze distributed traces, and query infrastructure metrics. Prefer this over Prometheus for APM data." ``` ```bash - holmes ask -t custom_toolset.yaml "Query my MCP server" + holmes ask -t custom_toolset.yaml "What services have high error rates in Dynatrace?" ``` Alternatively, add the config to `~/.holmes/config.yaml` and run without `-t`. @@ -42,21 +43,22 @@ HolmesGPT supports three MCP transport modes: ```yaml additionalEnvVars: - - name: MY_MCP_API_KEY + - name: DYNATRACE_API_KEY valueFrom: secretKeyRef: name: mcp-credentials key: api_key mcp_servers: - my_server: - description: "My MCP server" + dynatrace: + description: "Dynatrace observability platform" config: - url: "http://example.com:8000/mcp/messages" + url: "http://dynatrace-mcp:8000/mcp/messages" mode: streamable-http headers: - Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" - llm_instructions: "Use this server to access external data and perform remote operations." + Authorization: "Bearer {{ env.DYNATRACE_API_KEY }}" + # llm_instructions tells Holmes WHEN and HOW to use this server + llm_instructions: "Use Dynatrace to investigate application performance issues, analyze distributed traces, and query infrastructure metrics. Prefer this over Prometheus for APM data." ``` ```bash @@ -70,21 +72,22 @@ HolmesGPT supports three MCP transport modes: ```yaml holmes: additionalEnvVars: - - name: MY_MCP_API_KEY + - name: DYNATRACE_API_KEY valueFrom: secretKeyRef: name: mcp-credentials key: api_key mcp_servers: - my_server: - description: "My MCP server" + dynatrace: + description: "Dynatrace observability platform" config: - url: "http://example.com:8000/mcp/messages" + url: "http://dynatrace-mcp:8000/mcp/messages" mode: streamable-http headers: - Authorization: "Bearer {{ env.MY_MCP_API_KEY }}" - llm_instructions: "Use this server to access external data and perform remote operations." + Authorization: "Bearer {{ env.DYNATRACE_API_KEY }}" + # llm_instructions tells Holmes WHEN and HOW to use this server + llm_instructions: "Use Dynatrace to investigate application performance issues, analyze distributed traces, and query infrastructure metrics. Prefer this over Prometheus for APM data." ``` ```bash @@ -105,8 +108,8 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou ```yaml mcp_servers: - my_stdio_server: - description: "Custom stdio MCP server" + ticket_db: + description: "Internal ticket database" config: mode: stdio command: "python3" @@ -114,11 +117,12 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou - "./my_mcp_server.py" env: CUSTOM_VAR: "value" - llm_instructions: "Use this server to access custom tools provided by the stdio server." + # llm_instructions tells Holmes WHEN and HOW to use this server + llm_instructions: "Use this server to query the internal ticket database. Search for related incidents by error message or service name." ``` ```bash - holmes ask -t custom_toolset.yaml "Run my MCP server tools" + holmes ask -t custom_toolset.yaml "Find tickets related to payment service errors" ``` Ensure required dependencies (e.g., `mcp`, `fastmcp` packages) are installed in your environment. @@ -153,9 +157,9 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou apiVersion: v1 kind: Pod metadata: - name: my-mcp-server + name: ticket-db-mcp labels: - app: my-mcp-server + app: ticket-db-mcp spec: containers: - name: supergateway @@ -183,10 +187,10 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou apiVersion: v1 kind: Service metadata: - name: my-mcp-server + name: ticket-db-mcp spec: selector: - app: my-mcp-server + app: ticket-db-mcp ports: - protocol: TCP port: 8000 @@ -198,12 +202,13 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou ```yaml mcp_servers: - my_mcp_server: - description: "My stdio MCP server via Supergateway" + ticket_db: + description: "Internal ticket database" config: - url: "http://my-mcp-server.default.svc.cluster.local:8000/sse" + url: "http://ticket-db-mcp.default.svc.cluster.local:8000/sse" mode: sse - llm_instructions: "Use this server to access custom tools." + # llm_instructions tells Holmes WHEN and HOW to use this server + llm_instructions: "Use this server to query the internal ticket database. Search for related incidents by error message or service name." ``` ```bash @@ -240,9 +245,9 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou apiVersion: v1 kind: Pod metadata: - name: my-mcp-server + name: ticket-db-mcp labels: - app: my-mcp-server + app: ticket-db-mcp spec: containers: - name: supergateway @@ -270,10 +275,10 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou apiVersion: v1 kind: Service metadata: - name: my-mcp-server + name: ticket-db-mcp spec: selector: - app: my-mcp-server + app: ticket-db-mcp ports: - protocol: TCP port: 8000 @@ -289,9 +294,10 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou my_mcp_server: description: "My stdio MCP server via Supergateway" config: - url: "http://my-mcp-server.default.svc.cluster.local:8000/sse" + url: "http://ticket-db-mcp.default.svc.cluster.local:8000/sse" mode: sse - llm_instructions: "Use this server to access custom tools." + # llm_instructions tells Holmes WHEN and HOW to use this server + llm_instructions: "Use this server to query the internal ticket database. Search for related incidents by error message or service name." ``` ```bash @@ -306,24 +312,24 @@ SSE transport is deprecated. Use `streamable-http` for new integrations. ```yaml mcp_servers: - legacy_server: - description: "Legacy MCP server using SSE" + legacy_analytics: + description: "Legacy analytics platform (SSE transport)" config: - url: "http://example.com:8000/sse" + url: "http://analytics-mcp:8000/sse" mode: sse - llm_instructions: "Legacy server." + llm_instructions: "Query historical analytics data. Use for trend analysis over periods longer than 30 days." ``` === "Holmes Helm Chart" ```yaml mcp_servers: - legacy_server: - description: "Legacy MCP server using SSE" + legacy_analytics: + description: "Legacy analytics platform (SSE transport)" config: - url: "http://example.com:8000/sse" + url: "http://analytics-mcp:8000/sse" mode: sse - llm_instructions: "Legacy server." + llm_instructions: "Query historical analytics data. Use for trend analysis over periods longer than 30 days." ``` === "Robusta Helm Chart" @@ -355,14 +361,14 @@ MCP servers can use dynamic headers populated from the incoming HTTP request. Th ```yaml mcp_servers: - my_server: - description: "MCP server with dynamic auth" + customer_data: + description: "Customer data API (requires per-request auth)" config: - url: "http://mcp-server:8000/mcp" + url: "http://customer-api:8000/mcp" mode: streamable-http extra_headers: X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" - llm_instructions: "Use this server with per-request authentication." + llm_instructions: "Query customer account details and subscription status. Use when investigating user-reported issues." ``` === "Robusta Helm Chart" From 415ebc0859c696ead24ba4f85a176e471573399a Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Feb 2026 22:54:23 +0000 Subject: [PATCH 7/8] Fix inconsistent examples in Robusta Helm Chart sections - Fixed Stdio section: use ticket_db consistently, fixed llm_instructions indent - Fixed SSE section: use legacy_analytics with proper description - Fixed Advanced section: use customer_data consistently across tabs https://claude.ai/code/session_01H3xyWcwWem2ptcZjFaNs8n Signed-off-by: Claude --- docs/data-sources/remote-mcp-servers.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/data-sources/remote-mcp-servers.md b/docs/data-sources/remote-mcp-servers.md index 56eedd883a..66757d5b62 100644 --- a/docs/data-sources/remote-mcp-servers.md +++ b/docs/data-sources/remote-mcp-servers.md @@ -291,13 +291,13 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou ```yaml holmes: mcp_servers: - my_mcp_server: - description: "My stdio MCP server via Supergateway" + ticket_db: + description: "Internal ticket database" config: url: "http://ticket-db-mcp.default.svc.cluster.local:8000/sse" mode: sse # llm_instructions tells Holmes WHEN and HOW to use this server - llm_instructions: "Use this server to query the internal ticket database. Search for related incidents by error message or service name." + llm_instructions: "Use this server to query the internal ticket database. Search for related incidents by error message or service name." ``` ```bash @@ -337,12 +337,12 @@ SSE transport is deprecated. Use `streamable-http` for new integrations. ```yaml holmes: mcp_servers: - legacy_server: - description: "Legacy MCP server using SSE" + legacy_analytics: + description: "Legacy analytics platform (SSE transport)" config: - url: "http://example.com:8000/sse" + url: "http://analytics-mcp:8000/sse" mode: sse - llm_instructions: "Legacy server." + llm_instructions: "Query historical analytics data. Use for trend analysis over periods longer than 30 days." ``` The URL should end with `/sse`. If it doesn't, HolmesGPT will automatically append it. @@ -376,14 +376,14 @@ MCP servers can use dynamic headers populated from the incoming HTTP request. Th ```yaml holmes: mcp_servers: - my_server: - description: "MCP server with dynamic auth" + customer_data: + description: "Customer data API (requires per-request auth)" config: - url: "http://mcp-server:8000/mcp" + url: "http://customer-api:8000/mcp" mode: streamable-http extra_headers: X-Auth-Token: "{{ request_context.headers['X-Auth-Token'] }}" - llm_instructions: "Use this server with per-request authentication." + llm_instructions: "Query customer account details and subscription status. Use when investigating user-reported issues." ``` When making requests to HolmesGPT, include the required header: From 197afdb2ce24cb6184fb0d44aec4d3cfb9318761 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Feb 2026 04:34:08 +0000 Subject: [PATCH 8/8] Simplify CLI examples to use ~/.holmes/config.yaml Remove -t custom_toolset.yaml pattern from CLI examples. Show config added directly to ~/.holmes/config.yaml which is the standard approach. https://claude.ai/code/session_01H3xyWcwWem2ptcZjFaNs8n Signed-off-by: Claude --- docs/data-sources/remote-mcp-servers.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/data-sources/remote-mcp-servers.md b/docs/data-sources/remote-mcp-servers.md index 66757d5b62..2068340044 100644 --- a/docs/data-sources/remote-mcp-servers.md +++ b/docs/data-sources/remote-mcp-servers.md @@ -14,9 +14,7 @@ HolmesGPT supports three MCP transport modes: === "Holmes CLI" - Create a config file and pass it when running CLI commands. - - **custom_toolset.yaml:** + Add to `~/.holmes/config.yaml`: ```yaml mcp_servers: @@ -32,11 +30,9 @@ HolmesGPT supports three MCP transport modes: ``` ```bash - holmes ask -t custom_toolset.yaml "What services have high error rates in Dynatrace?" + holmes ask "What services have high error rates in Dynatrace?" ``` - Alternatively, add the config to `~/.holmes/config.yaml` and run without `-t`. - === "Holmes Helm Chart" Add to your Helm values: @@ -102,9 +98,7 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou === "Holmes CLI" - Create a config file and pass it when running CLI commands. - - **custom_toolset.yaml:** + Add to `~/.holmes/config.yaml`: ```yaml mcp_servers: @@ -114,7 +108,7 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou mode: stdio command: "python3" args: - - "./my_mcp_server.py" + - "/path/to/my_mcp_server.py" env: CUSTOM_VAR: "value" # llm_instructions tells Holmes WHEN and HOW to use this server @@ -122,7 +116,7 @@ Stdio mode runs MCP servers as subprocesses, communicating via standard input/ou ``` ```bash - holmes ask -t custom_toolset.yaml "Find tickets related to payment service errors" + holmes ask "Find tickets related to payment service errors" ``` Ensure required dependencies (e.g., `mcp`, `fastmcp` packages) are installed in your environment. @@ -310,6 +304,8 @@ SSE transport is deprecated. Use `streamable-http` for new integrations. === "Holmes CLI" + Add to `~/.holmes/config.yaml`: + ```yaml mcp_servers: legacy_analytics: