Configure a least-privileged API client

Plan the minimum Controller and Analytics Events permissions required by the MCP server.

Grant only the domains and entity scopes that the deployment uses. Returning an identifier from one domain does not require access to that domain; following the identifier into another tool does. For a cross-domain workflow, grant the union of the permissions for the tools that the workflow calls.

Separate Controller and Events Service credentials

  1. Controller tools use an AppDynamics Controller API-client OAuth bearer. The API client inherits the Controller roles attached to it, and each Controller API applies its own access checks. The generated client secret is a password used to obtain a token; it is not itself an access token.
  2. Analytics Events tools use a separate Events Service URL, one Global Account Name, and an Events API key. A Controller bearer or Controller Analytics role does not authorize an Events query.

Licensing, feature enablement, and data retention are separate from access control. An empty response does not prove that access is configured correctly.

Minimum domain access

Required is the normal read permission. Conditional applies only to the named feature or cross-domain follow-up. Verify means the product does not publish a distinct read-only boundary, so test an assigned and unassigned entity before relying on it.

Domain Required minimum Conditional access or verification
APM Applications > View on each required application. This covers application, tier, node, business-transaction, metric, flowmap, snapshot, health-rule, violation, and alerting-policy reads. Conditional: Dashboards > View for each custom dashboard. Cross-domain application inventory also needs the selected EUM and DBMon read grants. Metric-derived flowmaps do not need View Business Flow.
EUM Applications > View on each required Browser RUM or Mobile RUM application. Conditional: Synthetic entitlement and application visibility for Synthetic reads; an Events API key for Events-backed workflows; target APM View for APM enrichment or follow-up.
DBMon Databases > View on each required database. The predefined DB Monitoring User is a broader alternative. Conditional: Applications > View on the internal Database Monitoring application for learned-baseline enrichment; target APM View when an APM lookup or enrichment runs; SIM access only for a subsequent SIM call. VIEW_DBMON_UI alone does not grant data access.
SIM Without Tag-Based Access Control (TBAC), View Server Visibility (VIEW_SIM). With TBAC, use a Standard or Dynamic server role scoped to the required infrastructure. Conditional: Applications > View on the internal Server & Infrastructure Monitoring application for health-rule-violation and dynamic-metric reads; target APM View only for an APM follow-up. Verify: TBAC with assigned and unassigned machines, and remove broad legacy VIEW_SIM grants that can bypass tag scope.
Cluster Without TBAC, View Server Visibility (VIEW_SIM); there is no separate Cluster permission. With TBAC, use infrastructure-scoped Standard or Dynamic roles. Conditional: target APM View only for an APM follow-up. Verify: every enabled Cluster tool against assigned and unassigned infrastructure. Kubernetes permissions used by the Cluster Agent are separate from Controller API-client roles.
Analytics Events A separate Events API key with Query access to every selected event type and its application or source scope. The local event-type catalog needs no upstream grant. Grant only the applicable Transactions, Logs, Browser Requests, Mobile Requests, Synthetic Requests Permissions, Connected Devices Permissions, or Custom Analytics Events > Query Custom Events scope.
General Applications > View on the relevant application for anomalies, RCA, alerting policies, and application-scoped events. The local domain guide needs no upstream grant. Conditional: entity-appropriate VIEW_TAGS, dashboard View, or SIM visibility for tag tools; SIM visibility for infrastructure-tagged metrics; DBMon data read for DBMon event details. Verify: Controller entity-search and activity-event access because no separate named read action is published.

Create the custom role and API client

Create a custom Controller role and API client with only the permissions required for MCP workflows.

Create a new custom role instead of cloning a predefined role. Predefined roles can include broader permissions than their names suggest.
The administrator performing these steps needs Account Owner or permission to administer users, groups, and roles. The runtime API client does not.
  1. Open Settings > Administration > Roles > Create.
  2. Add only the domain grants and named entity scopes from the table above.

    On Applications, leave the default View off and turn on View only for each required application. Leave Create, Edit, Delete, and configuration actions turned off. Add VIEW_TAGS only when tag tools are enabled.

  3. Review every role attached to the client for inherited broad or default grants.

    A grant in any attached role wins even if another role denies it, so an existing broad role defeats a narrow custom role.

  4. Save the role, then open Settings > Administration > API Clients > Create.
  5. Generate the client secret, set the token-expiration policy, and attach only the reviewed read roles.
  6. Copy the secret into an approved secret store.

    The client secret is a password used to obtain access tokens; it is not itself an access token.

Obtain a Controller access token

Generate a temporary Controller access token or request one by using OAuth client credentials.

Choose either method.
From the Controller UI,
  1. Open the API client, select Generate Temporary Access Token, choose an expiry, and copy the token. Send this value as a bearer token. Previously issued tokens remain valid until their own expiry.
By using OAuth client credentials:
  1. APPD_CLIENT_ID is the API client name and APPD_CUSTOMER is the Controller account name. The server forms the OAuth client ID <apiClientName>@<accountName>.
    JSON 
    export APPD_ENVIRONMENT="https://your-controller.example.com/controller"
export APPD_CLIENT_ID="mcp-readonly"
export APPD_CUSTOMER="your-account-name"
export APPD_CLIENT_SECRET="<secret>"

curl --fail-with-body --silent --show-error \
  --request POST "$APPD_ENVIRONMENT/api/oauth/access_token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=${APPD_CLIENT_ID}@${APPD_CUSTOMER}" \
  --data-urlencode "client_secret=${APPD_CLIENT_SECRET}"

Obtain an Analytics Events key

Create a query-only Analytics Events API key for live Analytics Events tools.

Analytics Events uses a separate service and credential. An administrator with Analytics Manage APIs must create the key. Do not assign Manage APIs to the runtime Controller API client.
  1. Open Analytics > Configuration > API Keys.
  2. Select only the required query scopes, and create the key.

    You cannot change key permissions after you create the key.

  3. Copy the key before you close the dialog box.

    You cannot retrieve the key afterward.

Validate access

Verify least-privileged access across every enabled domain before you share the API client.

  1. Confirm that the API client can obtain a Controller token, and then call one narrow inventory tool in each enabled domain with that token.
  2. Test Analytics Events with its own key and every required event type and application or source scope.

    Controller token success does not validate Analytics Events authorization.