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.

CODE 
curl --fail --silent --show-error http://127.0.0.1:6350/health
docker logs -f appdynamics-mcp

Inspector tool

Use mcp-inspector to verify the server handshake and test individual tools without an AI client:

CODE 
npx @modelcontextprotocol/inspector \
  --header "Authorization: Bearer <Controller-token>" \
  http://localhost:6350/mcp

Common errors

Symptom Likely cause Action
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/Events certificate not trusted by the image Install or mount the correct CA trust and keep APPD_VERIFY_SSL=true.
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.