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

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:

CODE
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 SSL_CERT_FILE to a CA bundle containing the roots needed by the Controller and Events endpoints. Outbound certificate verification remains enabled.

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.