appd-mcp

What is this? A Model Context Protocol server, written in TypeScript, that exposes 12 read-only AppDynamics capabilities (applications, topology, metrics, snapshots, health rules, anomalies, events, alerting config, analytics events, dependency map) as task-oriented MCP tools an LLM agent can call directly. stdio transport, OAuth API-client credentials, no writes, no persistence beyond a local .env.

appd-mcp is not affiliated with, endorsed by, sponsored by, or certified by Cisco Systems, Inc., Splunk LLC, or AppDynamics, LLC. See TRADEMARKS.md.

Quickstart (60 seconds)

Requires Node 22+ and pnpm.

git clone https://github.com/jagalliers/appd-mcp.git
cd appd-mcp
pnpm install
pnpm build
pnpm wizard      # interactive wizard: prompts, validates, writes .env, registers in MCP host

v0.1.1 and earlier docs may say pnpm setup. That name was renamed to pnpm wizard in v0.1.2 because setup collides with pnpm's built-in command (it configures PNPM_HOME / PATH, not our wizard).

That's it. The wizard probes your live AppDynamics Controller before saving anything, refuses http:// URLs, won't run unattended (TTY required), and writes .env with 0600 perms plus a timestamped backup. Re-runs are idempotent.

If you'd rather configure by hand, see Documentation → Manual configuration below.

Tools

Status

Phase 1: read-only MVP. All 12 tools are read-only against the public AppDynamics Controller, Alerting, Anomaly Violation, and Events Service APIs.

Limitations and non-goals

This is intentionally a small, focused project. The following are out of scope for the current release:

• No write/change tools. Nothing in this server mutates AppDynamics state. Phase 3 will introduce write tools with per-tool allowlist + dryRun + confirm + audit gating; until then the server is provably read-only by construction.

• No sensitive-read tools. Audit logs, RBAC details, and PII surfaces are deferred to Phase 2.

• No on-prem auth modes yet. OAuth API-client credentials are the only auth path. Username + access-key, SAML federation, and on-prem proxy patterns are open questions in AGENT_BOOTSTRAP.md §8.

• No Synthetic. AppDynamics Synthetic monitoring tools are not in this MVP.

• No persistent server-side state. Caches are in-process LRU, resetting on restart.

• No production hosting opinion. The intended deployment is per-developer, per-MCP-host (Cursor or Claude Desktop on a workstation). Multi-tenant, internet-facing deployment is not a goal.

See AGENT_BOOTSTRAP.md for the full phase roadmap.

Documentation

• AGENT_BOOTSTRAP.md — canonical onboarding document (architecture, tool catalog, conventions, decision log, open questions). New devs/agents start here.

• CONTRIBUTING.md — dev setup, conventions, how to add a tool, PR expectations.

• SECURITY.md — vulnerability disclosure policy.

• CODE_OF_CONDUCT.md — Contributor Covenant v2.1.

• TRADEMARKS.md — independence statement and third-party trademark disclaimers.

• NOTICE and THIRD_PARTY_NOTICES.md — attribution for ported upstream code (the setup wizard ports from the Apache-2.0 spl-bridge project).

• docs/wizard-pty-validation/ — archived POSIX-only PTY harness for hand-iterating wizard prompts; not part of CI.

Setup wizard

pnpm wizard runs an interactive wizard that drops you into a working install in five steps:

1. Prerequisites — checks Node version, that dist/index.js exists, and that .env is writable. Detects Cursor / Claude Desktop installations.

2. Collect — prompts for Controller URL, account name (auto-suggested from the URL's leftmost label), API Client ID, and API Client Secret. Optionally collects Events Service URL and key. Always re-prompts secrets across retries.

3. Probe — exercises the OAuth endpoint, lists applications via the Controller, and (if events were configured) issues a smoke ADQL. A failure shows the exact endpoint and offers Edit / Save-anyway / Quit, bounded to 3 attempts. A 500 Error provisioning account on any cluster on the Events probe degrades to SKIP (the tenant simply isn't entitled for Analytics) instead of failing the wizard.

4. Persist — atomic-write .env with a timestamped .bak.<ISO> and chmod 0600. Pre-validates against the Zod runtime schema before writing.

5. MCP host wiring — pick from Cursor (project), Cursor (user), or Print snippet only. The chosen target uses Cursor's native envFile field so no secrets land in mcp.json.

The wizard refuses to run when stdin is not a TTY (no piping secrets) and rejects http:// URLs as a hard-stop. Exit codes: 0 success, 1 user-driven abort, 2 safety-gate decline / non-TTY.

To verify a saved .env against the live Controller without reconfiguring anything, run:

pnpm wizard-live-probe

Manual configuration

If you don't want to use pnpm wizard, all configuration is via environment variables. See .env.example for the full list. Required:

• APPD_CONTROLLER_URL — the AppDynamics Controller base URL.

• APPD_ACCOUNT_NAME — your tenant name.

• APPD_API_CLIENT_ID / APPD_API_CLIENT_SECRET — OAuth API Client credentials (create in the Controller UI under Settings → Administration → API Clients).

Optional:

• APPD_EVENTS_SERVICE_URL / APPD_EVENTS_API_KEY — only needed for appd_query_analytics_events.

• APPD_TIMEOUT_MS, APPD_LOG_LEVEL, APPD_TOOLS_ENABLED — tuning.

Then start the server directly:

node --env-file=.env dist/index.js

Wiring into a host

Cursor (recommended path)

Cursor supports both workspace-scoped (<repo>/.cursor/mcp.json, ships with the repo) and user-scoped (~/.cursor/mcp.json, applies globally) MCP config. For dev-on-this-repo use, the workspace scope is cleanest because it uses Cursor's ${workspaceFolder} variable and Cursor's native envFile support — no absolute paths.

<repo>/.cursor/mcp.json:

{
  "mcpServers": {
    "appdynamics": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Then, in Cursor:

1. Run pnpm install && pnpm build once, and create .env (see Manual configuration).

2. Restart Cursor (or reload the window).

3. Open Settings → Tools & MCP (Cmd+Shift+J → Features → Model Context Protocol). Toggle the appdynamics server on.

4. The 12 appd_* tools become available to the agent. The agent will ask for confirmation before invoking them by default; Output → MCP Logs is the place to debug if a server fails to start.

This repo's default .gitignore excludes .cursor/, so .cursor/mcp.json does not get committed — paste the snippet above into your own checkout.

User-scoped config (~/.cursor/mcp.json) is functionally similar but ${workspaceFolder} doesn't help, so use absolute paths there. See the Cursor MCP docs for details.

pnpm wizard writes either of these for you.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "appdynamics": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/appd_mcp/.env",
        "/absolute/path/to/appd_mcp/dist/index.js"
      ]
    }
  }
}

Note that Claude Desktop does not currently honor an envFile field, so absolute paths are required.

Development

pnpm install         # one-time
pnpm lint            # biome check
pnpm typecheck       # tsc --noEmit
pnpm test            # vitest run (uses undici.MockAgent — no live AppD calls)
pnpm test:watch      # vitest in watch mode
pnpm build           # tsc -p tsconfig.build.json → dist/
pnpm smoke           # spawn dist/index.js, drive initialize + tools/list (no live AppD calls)
pnpm test:wizard     # in-process behavioral spot-checks for the setup wizard (requires build)

CI (GitHub Actions, see .github/workflows/ci.yml) runs lint → typecheck → test → build → smoke → test:wizard → pnpm audit --audit-level high on every push/PR to main.

Architecture, conventions, decision log, and open questions all live in AGENT_BOOTSTRAP.md. New agents/devs should start there.

Live integration testing

Once you have an AppDynamics tenant + API client credentials, you can exercise all 12 tools end-to-end against a real Controller. The integration runner spawns dist/index.js via the MCP client SDK (the same transport Claude Desktop / Cursor use) and drives a 17-step scenario across health, per-app deep walk, alerting, aggregation, skippable surfaces, and negative paths.

# 1. Drop creds into a local .env (gitignored) — or use `pnpm wizard`.
cp .env.example .env
# edit .env:
#   APPD_CONTROLLER_URL=https://<tenant>.saas.appdynamics.com
#   APPD_API_CLIENT_ID=<api-client-name>
#   APPD_API_CLIENT_SECRET=<secret>

# 2. Confirm the controller's accountName by probing the OAuth endpoint.
#    Tries the subdomain first (e.g. `<tenant>` for SaaS), then `customer1`.
#    If APPD_ACCOUNT_NAME is already set, only that one is tried.
pnpm probe-account
# → prints `APPD_ACCOUNT_NAME=<resolved>` on success.

# 3. Build (ensures dist/ matches src/) and run the full integration walk.
pnpm build
pnpm integration

Per-step JSON artifacts and a combined report.json land under tmp/integration/<ISO-timestamp>/ (gitignored). The runner also captures the spawned server's stderr and asserts that the literal APPD_API_CLIENT_SECRET value never appears in it (defense-in-depth on top of the pino redaction unit tests).

The runner does not run in CI: it requires a long-lived secret and hits a live tenant. Run it locally before any release.

After a successful run, rotate the API client secret in the Controller UI (Administration → API Clients → Generate Secret) — especially if the credential ever transited a chat or shared terminal.

Security

• No hardcoded secrets. All credentials via env vars.

• OAuth tokens are never logged (pino redaction is mandatory).

• stdio transport only — stdout reserved for MCP frames, logs go to stderr.

• TLS verification on by default. APPD_INSECURE_SKIP_VERIFY=true exists for dev-only and must never be used in production.

For vulnerability disclosure, see SECURITY.md. The full list of conventions lives in AGENT_BOOTSTRAP.md §6 Conventions.

License

MIT. Portions of src/setup/ are ported from the Apache-2.0 licensed spl-bridge project; see NOTICE and THIRD_PARTY_NOTICES.md.