Common Issues
Diagnose process, authentication, configuration, size-limit, and connectivity problems with the MCP server.
Check health and logs
Container logs stream to stdout and to APPD_LOGFILE inside the container.
curl --fail --silent --show-error http://127.0.0.1:6350/health
docker logs -f appdynamics-mcp
File output requires APPD_LOGFILE; otherwise use process logs.
Inspector tool
Use mcp-inspector to verify the server handshake and test individual tools without an AI client:
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:6350/mcp \
--transport http --header "Authorization: Bearer <Controller-token>" --method tools/list
A completed MCP/HTTP exchange can contain a tool error or partial data. Check ok, status, error and coverage. retryable is a caller hint, not an automatic retry or guarantee of recovery.
Send Authorization and, in multi-controller mode, X-AppD-Controller-Host. Add the mode-specific Events headers from the client examples when needed.
Common errors
| Symptom | Likely cause | Action |
|---|---|---|
| Multi-controller startup conflict | Unset APPD_ENVIRONMENT, APPD_ANALYTICS_EVENTS_URL and APPD_ANALYTICS_EVENTS_GLOBAL_ACCOUNT_NAME. Each client sends its Controller and, for live Events, Events targets in headers. |
|
| Target-header error | Fixed mode must omit X-AppD-Controller-Host, X-AppD-Analytics-Events-URL and X-Events-API-AccountName. |
Multi-controller mode requires X-AppD-Controller-Host; live Events also requires X-AppD-Analytics-Events-URL, X-Events-API-AccountName and X-Events-API-Key. |
| Incomplete listener TLS pair | Configure both certificate and key, or neither behind trusted TLS termination. | |
| Remote client cannot reach wheel/source HTTP | Direct remote listening needs non-loopback MCP_HOST and TLS/network controls; a local TLS proxy can retain loopback. |
|
| CAT tool missing | Enable CAT, restart and refresh the catalog. | |
| CAT rejects OAuth | Use HTTP request_bearer or stdio env_bearer with an issued token. |
|
| CAT busy | Wait for the active run before retrying. | |
| CAT timeout or reported limit | Confirm the actual cause; check waits and workload sizing before raising a matching limit. | |
| CAT incomplete evidence or unknown grades | Check failed sources, permissions and reported limits. Missing evidence is not proof of a configuration defect. | |
| Container exits during startup | Missing Controller environment, incompatible APPD_AUTH_MODE, or incomplete stdio credentials |
Match the transport/auth table exactly and inspect logs. |
| HTTP 401 before a tool runs | Missing or malformed Authorization header |
Send Authorization: Bearer <Controller-token>. |
HTTP 400 for X-AppD-Environment |
Client attempted a caller-controlled Controller URL | Remove the header; the Controller URL is server-owned. |
| Controller 401/403 | Invalid/expired credential or insufficient scope | Rotate/correct the credential or roles; do not broaden to administrator by default. |
| Analytics configuration error | Missing Events URL/account/key, or key omitted from an HTTP request | Configure the server-owned account name and supply the transport-appropriate Events key. |
| Analytics 401/403 or schema/query failure | Events key lacks Query permission for the selected event type/scope, or the type/field differs | Verify grants and run the live field descriptor; do not fall back to Controller ADQL. |
| TLS verification failure | Controller and Events certificate not trusted by the image |
Set |
APPD_RESPONSE_TOO_LARGE |
A Controller response exceeded its configured ceiling, or an Analytics Events response exceeded its fixed 2 MiB ceiling | Narrow the entity, path, depth, time, fields, or row limit. Change APPD_CONTROLLER_MAX_RESPONSE_BYTES only for Controller responses. |
| Controller metric HTTP 429 with data-point details | The time range or number of metric paths exceeded the point budget | Reduce the time range or number of exact metric paths; this limit is non-retryable. |
| EUM rank validation error | Zero/multiple/partial wildcards, rollup=true, a comparison, a window over 24 hours, or over 500 series |
Discover exact paths first, use one complete child wildcard, keep rollup=false, and narrow the window/parent. |
| Empty list/series | No data, incorrect identity or time window, monitoring turned off, expired retention, or insufficient permission | Check status, errors, coverage, truncation, exact IDs/paths, and epoch bounds before interpreting. |
/health succeeds but tools fail |
Health does not test downstream services | Run one bounded Controller call and, if configured, one minimized Events read. |
| Client cannot read resources | MCP client lacks resource support | Use get_appdynamics_domain_guide with a supported guide topic. |