AppDynamics MCP Server

A Model Context Protocol server that gives LLM clients (Cursor, Claude Desktop, etc.) full access to your AppDynamics monitoring data — plus the ability to create and manage dashboards and health rules.

Features

30 tools across 8 categories:

• Discovery: List and search applications by name

• Health Monitoring: Full health rule CRUD, violations, and anomaly detection

• Application Performance: Business transactions, service endpoints, and their metrics

• Infrastructure: Tiers, nodes, and backend/remote service dependencies

• Diagnostics: Transaction snapshots and error events

• Root Cause Analysis: Automated composite diagnosis across all signal types

• Metrics: Browse the metric tree and query any metric with rollup support

• Dashboards: Full CRUD — list, view, create, update, add widgets, clone, delete, export, import, auto-build, per-rule health status widgets

Key capabilities

• Natural language friendly: Accept application names, not just IDs

• Historical time ranges: Query any past window, not just "the last N minutes" — see Time Ranges

• Metric tree browser: Discover available metrics interactively, including custom/machine-agent metrics

• Rollup control: Per-widget rollup for time-series vs. aggregate metric views

• Dashboard auto-builder: Create full multi-section dashboards from a single prompt

• HealthListWidget scoping: Each widget can be pinned to a specific health rule (not "all rules")

• Health rule CRUD: Create, update, enable/disable, and delete health rules — including custom metrics scoped to a specific tier or node

• Smart defaults: Sensible time ranges and result limits out of the box

Related MCP server: Observe MCP Server

Time Ranges

Every time-aware tool accepts durationInMins, startTime, and endTime. Timestamps may be ISO 8601 (2026-08-03T14:00:00Z) or epoch milliseconds; bare epoch-seconds values are detected and converted.

// "What did response time look like during yesterday's incident?"
{
  "application": "Checkout",
  "metricPath": "Overall Application Performance|Average Response Time (ms)",
  "startTime": "2026-08-02T12:00:00Z",
  "endTime":   "2026-08-02T15:00:00Z"
}

Contradictory input is rejected with an actionable message rather than silently guessing — supplying durationInMins together with both endpoints, an inverted window (endTime before startTime), or an unparseable timestamp all return an error.

Tools supporting time ranges: appd_get_metric_data, appd_get_health_violations, appd_get_anomalies, appd_get_errors, appd_get_snapshots, appd_get_bt_performance, appd_get_service_endpoint_performance, appd_diagnose_issue.

Note: AppDynamics rolls older data into coarser buckets. A narrow window far in the past may return nothing even though a wider window over the same period returns an aggregate — this is controller-side retention granularity, not a query error.

Quick Start

1. Install dependencies

npm install

2. Configure environment

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Required variables:

3. Add to your MCP client

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "appdynamics": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/appdynamics-mcp-server",
      "env": {
        "APPD_URL": "https://your-controller.saas.appdynamics.com",
        "APPD_CLIENT_NAME": "your-client-name",
        "APPD_CLIENT_SECRET": "your-client-secret",
        "APPD_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "appdynamics": {
      "command": "npx",
      "args": ["tsx", "/path/to/appdynamics-mcp-server/src/index.ts"],
      "env": {
        "APPD_URL": "https://your-controller.saas.appdynamics.com",
        "APPD_CLIENT_NAME": "your-client-name",
        "APPD_CLIENT_SECRET": "your-client-secret",
        "APPD_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

Tools Reference

Discovery

Health Monitoring

Application Performance

Infrastructure

Diagnostics

Root Cause Analysis

Metrics

Dashboards

Dashboard widget types

Widgets are saved first, then their metric bindings are attached in a second pass using the server-assigned widget ids — this is what makes graphs actually render data. Metric paths are bound in one of three forms (each verified against the dashboard rendering API): Business Transaction metrics with btIds use BT criteria; app-scope metrics (Overall Application Performance, Backends, Service Endpoints, …) use the application-aggregate criteria, optionally scoped per tier via tierIds; node metrics (JVM, Hardware Resources, or Application Infrastructure Performance|Tier|… paths) use node-level criteria with the node-relative path.

Example Conversations

"What's the health status of my production apps?" → Uses appd_get_applications + appd_get_health_violations + appd_get_anomalies

"Show me the slowest business transactions for the Orders app" → Uses appd_get_business_transactions + appd_get_bt_performance

"What databases does the Payment service connect to?" → Uses appd_get_backends with typeFilter="JDBC"

"Create a health rule that fires when Custom Metrics|RequestCount > 1000 on the WebTier" → Uses appd_create_health_rule with affectedEntityType="TIER_NODE_HEALTH", affectedTier="WebTier", metricPath="Custom Metrics|RequestCount"

"Create a dashboard for the Checkout app with response time and error rate" → Uses appd_get_applications → appd_browse_metric_tree → appd_create_dashboard

"Build me a full monitoring dashboard for the Orders app" → Uses appd_auto_build_dashboard — auto-discovers all tiers, BTs, and health rules, creates a complete dashboard in one shot

"Create one health widget per URL Monitor service, each scoped to its own rule" → Uses appd_create_health_rule (one per service) + appd_create_dashboard with healthRuleIds on each HEALTH_LIST widget

"Clone the production monitoring dashboard for staging" → Uses appd_get_dashboards → appd_clone_dashboard

"Why is my Payment app slow? Diagnose the last hour" → Uses appd_diagnose_issue with application="Payment", durationInMins=60 — returns ranked root cause candidates, merged event timeline, error class breakdown, and step-by-step investigation guide

"Are there any errors spiking in the Orders app right now?" → Uses appd_diagnose_issue with application="Orders", focus="errors"

"What went wrong during yesterday's outage between 14:00 and 15:00?" → Uses appd_diagnose_issue with startTime/endTime — degradation is measured against the 14:00-preceding hour, so the report reflects that incident rather than current state

"Pull the snapshots captured during last Tuesday's slowdown" → Uses appd_get_snapshots with startTime/endTime

Health Rules — Custom Metrics

Custom metrics reported by machine agents are stored per-node under:

Application Infrastructure Performance|{Tier}|Individual Nodes|{Node}|Custom Metrics|{MetricName}

When creating health rules for custom metrics, use affectedEntityType=TIER_NODE_HEALTH and provide the relative metric path (not the full absolute path):

affectedEntityType: "TIER_NODE_HEALTH"
affectedNode: "my-server-hostname"          # scope to specific node
metricPath: "Custom Metrics|MyMetric"       # relative path only

Architecture

src/
├── index.ts              # Entry point, registers all tools
├── types.ts              # TypeScript interfaces
├── constants.ts          # Shared constants
├── services/
│   ├── auth.ts           # OAuth2 token management
│   └── api-client.ts     # Authenticated HTTP client
├── utils/
│   ├── error-handler.ts  # Error → MCP response
│   ├── app-resolver.ts   # App name → ID resolution
│   ├── time-range.ts     # Shared time-range parsing → AppD query params
│   ├── concurrency.ts    # Bounded fan-out across apps/tiers
│   └── formatting.ts     # Response formatting
└── tools/                # One file per tool domain
    ├── applications.ts
    ├── health-rules.ts        # CRUD + enable/disable
    ├── health-violations.ts
    ├── anomalies.ts
    ├── business-transactions.ts
    ├── bt-performance.ts
    ├── service-endpoints.ts
    ├── service-endpoint-paths.ts # pure SEP metric-tree paths + matching
    ├── tiers-nodes.ts
    ├── backends.ts
    ├── snapshots.ts
    ├── errors.ts
    ├── metrics.ts             # browse + query with rollup
    ├── dashboards.ts          # full CRUD + auto-build + HealthListWidget scoping
    ├── root-cause.ts
    └── root-cause-analysis.ts # pure correlation, scoring, narration

Development

# Run in dev mode (auto-reload)
npm run dev

# Build TypeScript
npm run build

# Run built version
npm start

# Unit tests — payload builders and root-cause analysis vs. ground-truth
# fixtures, plus SEP metric paths, application resolution, time-range
# resolution, response truncation, token caching, bounded concurrency,
# and error handling
npm test

# End-to-end verification: drives the MCP server against the live controller,
# creates test dashboards, and asserts the persisted widget shapes.
# Requires APPD_* env vars.
node scripts/verify-dashboard-fixes.mjs

CI runs the typecheck, the unit tests, and a server-startup smoke check on every push and pull request, plus a gitleaks secret scan over the full history. See .github/workflows/ci.yml.

Authentication

The server supports two authentication modes:

1. OAuth2 Client Credentials (recommended): Set APPD_CLIENT_NAME, APPD_CLIENT_SECRET, and optionally APPD_ACCOUNT_NAME. The server acquires and caches tokens automatically.

2. API Key: Set only APPD_CLIENT_NAME (as the API key). No secret needed.

Token handling details:

• Tokens are cached until 5 minutes before expiry.

• Concurrent callers share a single in-flight token request, so a cold start issues one OAuth exchange rather than one per parallel tool call.

• A 401 invalidates the cached token and retries the request once with a fresh one — a token revoked before its advertised expiry recovers automatically instead of failing every call until the cache times out.

• Credentials are never written to logs or error messages; OAuth failures log only the HTTP status code.

Never commit credentials. Keep them in .env (gitignored) or your MCP client's env block. If a secret is ever committed, rotate it in the AppDynamics controller — removing it from git history alone does not invalidate it.

Reliability

• Bounded fan-out: tools that sweep every application or tier cap simultaneous requests (MAX_CONCURRENT_REQUESTS, default 6) instead of firing one request per entity at once, which trips controller rate limiting on large accounts.

• Budgeted truncation: oversized responses are trimmed to the largest prefix that fits CHARACTER_LIMIT, and the note reports how many of the total items were kept.

• Capped error bodies: upstream error payloads (including HTML error pages) are collapsed to a single line and truncated before being surfaced.

License

ISC