--- name: dynatrace-managed description: Set up and query Dynatrace Managed (self-hosted) through the Dynatrace Managed MCP server - configuring cluster connections and API tokens, choosing the right environment when several are configured, and building entity selectors for logs, metrics, events, problems, security vulnerabilities and SLOs. Use when the user mentions Dynatrace, Dynatrace Managed, observability data for their services, or when a dynatrace_managed_* tool returns a configuration or connection error. license: Apache-2.0 compatibility: Requires Node.js and network access to a Dynatrace Managed cluster API endpoint. metadata: author: dynatrace-oss --- # Dynatrace Managed Guidance for driving the `dynatrace-managed` MCP server. The server sends its own detailed tool instructions on connect - this skill covers what it cannot: getting it configured, and adapting queries to this repository's own components and tagging strategy. ## First: is it configured? The server exits at startup unless exactly one configuration source is present. If tool calls fail with `Configuration not found`, or `dynatrace_managed_get_environments_info` reports configuration errors, the user needs to supply credentials - no amount of retrying will fix it. When installed as a plugin, the client prompts for `DT_ENVIRONMENT_CONFIGS` up front and injects it into the server, so this is usually already handled. Outside that flow there are two mutually exclusive options, in priority order: 1. **`DT_CONFIG_FILE`** - path to a JSON or YAML file describing the environments. Preferred for more than one cluster. Write `apiToken: ${DT_PROD_TOKEN}` and the loader interpolates that variable at runtime, so the file itself stays free of secrets and can be committed. 2. **`DT_ENVIRONMENT_CONFIGS`** - a JSON array as a single environment variable. Preferred for one cluster and for containerized setups. Setting both logs a warning and `DT_CONFIG_FILE` wins. Minimal `DT_ENVIRONMENT_CONFIGS` value: ```json [ { "alias": "production", "apiEndpointUrl": "https://dynatrace.example.com", "environmentId": "abc12345-1234-1234-1234-123456789abc", "apiToken": "dt0c01...." } ] ``` The API token needs read-only scopes. Point the user at [docs/api_token_scopes.md](https://github.com/dynatrace-oss/dynatrace-managed-mcp/blob/main/docs/api_token_scopes.md) rather than guessing which scopes a given tool requires, and at [docs/environment_variables.md](https://github.com/dynatrace-oss/dynatrace-managed-mcp/blob/main/docs/environment_variables.md) for the full variable list. Never write a real API token into a file that is tracked by git, and never echo one back in chat. ## Always start with the environment list Call `dynatrace_managed_get_environments_info` before any other tool. It returns the configured aliases along with per-environment connection and configuration errors. **Report those errors to the user before doing anything else** - a partially reachable cluster produces silently incomplete answers. Every subsequent tool call takes an `environment_alias`. Use `ALL_ENVIRONMENTS` only when the user genuinely wants every cluster fanned out; it multiplies load on self-hosted infrastructure. ## Picking the right environment Two ambiguities cause most wrong answers here: - **Managed vs. SaaS.** A user may have this server _and_ a Dynatrace SaaS MCP server configured at once. These are different backends with different data. If it is not obvious which one the question is about, ask. Some organizations have migrated to SaaS and keep Dynatrace Managed only as a historical archive - in that case live questions belong to SaaS. - **Which cluster.** Refer to environments by the `alias` from the configuration, and state in the answer which environment the data came from. Do not average or merge results across environments without saying so. ## Keeping queries cheap Dynatrace Managed is self-hosted, so an expensive query degrades the user's own cluster. - Use narrow relative time ranges: `now-1h`, `now-24h`. Reach for `now-7d` or wider only when the question is explicitly historical. - Filter at the source with an `entitySelector` instead of retrieving broadly and post-filtering. - When the user names a count ("the first 25 errors"), set `limit` - do not approximate with `searchText`. - Use problem IDs in UUID form from `dynatrace_managed_list_problems`, not the `P-XXXXX` display IDs. ## Entity selectors `dynatrace_managed_discover_entities` always requires an `entitySelector`, and a selector may name **exactly one** entity type. Comma-separated criteria are ANDed. ```text type("SERVICE"),entityName.contains("checkout") type("SERVICE"),tag("environment:production"),tag("app:checkout") type("HOST"),healthState("HEALTHY"),mzName("Production") type("AWS_LAMBDA_FUNCTION"),tag("AWS_REGION:us-west-2") entityId("SERVICE-123","SERVICE-456") ``` Invalid, and worth recognizing before the API rejects them: ```text type(SERVICE),type(PROCESS_GROUP) # only one type per query entityName("my-service") # type() required unless entityId() is used entityId("ID1") or entityId("ID2") # no OR; pass both IDs to one entityId() ``` ### Adapt this to the repository Replace the placeholders below with the components and tags actually in use, and keep the list next to whatever else describes this system. A selector tuned to real tags is the single biggest quality win available here. ```text Services: type("SERVICE"),tag("app:") Process groups: type("PROCESS_GROUP"),entityName.contains("") Containers: type("CONTAINER_GROUP_INSTANCE"),entityName.contains("") Hosts: type("HOST"),tag("environment:production"),tag("app:") ``` If the tagging strategy is unknown, discover it first with `dynatrace_managed_list_entity_types` and `dynatrace_managed_get_entity_type_details` rather than inventing tag keys. ## Log queries Simple form: a case-insensitive text search, e.g. `error`. Structured form, which can be combined with `AND`: ```text content="error" AND dt.entity.host="HOST-94A1B472D04D89D9" ``` ## Workflows | Goal | Sequence | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Incident investigation | `list_problems` -> `get_problem_details` | | Security assessment | `list_security_problems` -> `get_security_problem_details` | | SLO / error budget | `list_slos` -> `get_slo_details` | | Entity exploration | `list_entity_types` -> `discover_entities` -> `get_entity_details` -> `list_problems` or `list_events` scoped by that entity ID | All tool names carry the `dynatrace_managed_` prefix. Each response ends with a `Next Steps` footer - read it, it names the tool that usefully follows.