Configure an MCP client

Configure an MCP client for streamable HTTP or stdio and verify access to server capabilities.

Choose one supported transport and authentication combination.

Connection Required Controller credential Optional Analytics Events credential
Streamable HTTP Authorization: Bearer <AppDynamics-Controller-token> X-Events-API-Key: <Analytics-Events-key>
Stdio with env_bearer APPD_API_TOKEN EVENTS_API_KEY
Stdio with oauth APPD_CLIENT_ID, APPD_CLIENT_SECRET, and APPD_CUSTOMER EVENTS_API_KEY

The Analytics Events credential is required only for live Analytics Events tools.

Streamable HTTP client

The HTTP server must already be running with MCP_TRANSPORT=streamable-http, and the request_bearer authentication mode. Require APPD_ENVIRONMENT only for fixed HTTP; multi-controller HTTP supplies Controller/Events targets through headers

Claude JSON configuration

Fixed-controller endpoint
The server owns Controller/Events targets; the client supplies credentials.
JSON
{
  "mcpServers": {
    "appdynamics_fixed": {
      "url": "https://<fixed-mcp-host>/mcp",
      "headers": {
        "Authorization": "Bearer <controller-token>",
        "X-Events-API-Key": "<events-key>"
      }
    }
  }
}
Multi-controller endpoint
Two named connections share one endpoint, each with its own matching Controller/Events tuple.
JSON
{
  "mcpServers": {
    "appdynamics_controller_a": {
      "url": "https://<multi-mcp-host>/mcp",
      "headers": {
        "Authorization": "Bearer <controller-a-token>",
        "X-AppD-Controller-Host": "<controller-a-host>",
        "X-AppD-Analytics-Events-URL": "https://<events-a-host>",
        "X-Events-API-AccountName": "<controller-a-global-account-name>",
        "X-Events-API-Key": "<controller-a-events-key>"
      }
    },
    "appdynamics_controller_b": {
      "url": "https://<multi-mcp-host>/mcp",
      "headers": {
        "Authorization": "Bearer <controller-b-token>",
        "X-AppD-Controller-Host": "<controller-b-host>",
        "X-AppD-Analytics-Events-URL": "https://<events-b-host>",
        "X-Events-API-AccountName": "<controller-b-global-account-name>",
        "X-Events-API-Key": "<controller-b-events-key>"
      }
    }
  }
}

Authorization is required. X-Events-API-Key is optional and enables access to live Analytics Events tools when the server also has the corresponding Events URL and Global Account Name configured.

For live fixed-mode Events access, enable both optional Events exports in the server profile above. For Controller-only access, omit X-Events-API-Key in fixed mode and all three Events headers in multi-controller mode. Events URLs are base origins, without /events or /events/query. For a fixed server, do not send the Controller-host or Events-origin/account selectors.

Codex TOML configuration

Fixed-controller mode

Set the credentials in the environment that starts Codex:

BASH
export APPD_CONTROLLER_TOKEN="<AppDynamics-Controller-token>"
export APPD_EVENTS_API_KEY="<Analytics-Events-key>"  # Optional

Add the server to ~/.codex/config.toml:

TOML
[mcp_servers.appdynamics]
url = "https://your-mcp-endpoint.example.com/mcp"
bearer_token_env_var = "APPD_CONTROLLER_TOKEN"
env_http_headers = { "X-Events-API-Key" = "APPD_EVENTS_API_KEY" }
Multi-controller mode
BASH
export APPD_A_TOKEN='<controller-a-token>'
export APPD_A_EVENTS_KEY='<controller-a-events-key>'
export APPD_B_TOKEN='<controller-b-token>'
export APPD_B_EVENTS_KEY='<controller-b-events-key>'
Add the server to ~/.codex/config.toml:
TOML
[mcp_servers.appdynamics_controller_a]
url = "https://<multi-mcp-host>/mcp"
bearer_token_env_var = "APPD_A_TOKEN"
http_headers = { "X-AppD-Controller-Host" = "<controller-a-host>", "X-AppD-Analytics-Events-URL" = "https://<events-a-host>", "X-Events-API-AccountName" = "<controller-a-global-account-name>" }
env_http_headers = { "X-Events-API-Key" = "APPD_A_EVENTS_KEY" }
tool_timeout_sec = 120 # use 360 or more on entries used for CAT

[mcp_servers.appdynamics_controller_b]
url = "https://<multi-mcp-host>/mcp"
bearer_token_env_var = "APPD_B_TOKEN"
http_headers = { "X-AppD-Controller-Host" = "<controller-b-host>", "X-AppD-Analytics-Events-URL" = "https://<events-b-host>", "X-Events-API-AccountName" = "<controller-b-global-account-name>" }
env_http_headers = { "X-Events-API-Key" = "APPD_B_EVENTS_KEY" }
tool_timeout_sec = 120 # use 360 or more on entries used for CAT

The env_http_headers setting is optional and is required only for live Analytics Events access.

Stdio client with environment bearer authentication

The MCP client starts the container and supplies the Controller bearer token through the child-process environment. Stdio does not use MCP request headers.

Claude JSON configuration

JSON
{
  "mcpServers": {
    "appdynamics": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env", "MCP_TRANSPORT=stdio",
        "--env", "APPD_AUTH_MODE=env_bearer",
        "--env", "APPD_ENVIRONMENT",
        "--env", "APPD_API_TOKEN",
        "appdynamics/appdynamics-mcp-server:latest"
      ],
      "env": {
        "APPD_ENVIRONMENT": "https://your-controller.example.com/controller",
        "APPD_API_TOKEN": "<AppDynamics-Controller-token>"
      }
    }
  }
}
If you installed Python wheel package, use the following configuration:
JSON
{
  "mcpServers": {
    "appdynamics_controller_a": {
      "command": "/absolute/path/appd-mcp-venv/bin/appdynamics-mcp-server",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "APPD_AUTH_MODE": "env_bearer",
        "APPD_MULTI_CONTROLLER_ENABLED": "false",
        "APPD_ENVIRONMENT": "https://<controller-a-host>/controller",
        "APPD_API_TOKEN": "<controller-a-token>"
      }
    }
  }
}
If you installed Python wheel package, use the following configuration:
JSON
{
  "mcpServers": {
    "appdynamics_controller_a": {
      "command": "/absolute/path/appd-mcp-venv/bin/appdynamics-mcp-server",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "APPD_AUTH_MODE": "oauth",
        "APPD_MULTI_CONTROLLER_ENABLED": "false",
        "APPD_ENVIRONMENT": "https://<controller-a-host>/controller",
        "APPD_CLIENT_ID": "<API-client-name>",
        "APPD_CLIENT_SECRET": "<API-client-secret>",
        "APPD_CUSTOMER": "<AppDynamics-account-name>"
      }
    }
  }
}

Codex TOML configuration

Set the Controller values in the environment that starts Codex:

BASH
export APPD_ENVIRONMENT="https://your-controller.example.com/controller"
export APPD_API_TOKEN="<AppDynamics-Controller-token>"

Add the server to ~/.codex/config.toml:

TOML
[mcp_servers.appdynamics]
command = "docker"
args = [
  "run", "--rm", "-i",
  "--env", "MCP_TRANSPORT=stdio",
  "--env", "APPD_AUTH_MODE=env_bearer",
  "--env", "APPD_ENVIRONMENT",
  "--env", "APPD_API_TOKEN",
  "appdynamics/appdynamics-mcp-server:latest"
]
env_vars = ["APPD_ENVIRONMENT", "APPD_API_TOKEN"]

Stdio client with OAuth authentication

In this mode, the MCP server uses the configured AppDynamics API Client credentials to obtain and refresh the Controller token. This is downstream Controller OAuth, not MCP transport OAuth.

Claude JSON configuration

JSON
{
  "mcpServers": {
    "appdynamics": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env", "MCP_TRANSPORT=stdio",
        "--env", "APPD_AUTH_MODE=oauth",
        "--env", "APPD_ENVIRONMENT",
        "--env", "APPD_CLIENT_ID",
        "--env", "APPD_CLIENT_SECRET",
        "--env", "APPD_CUSTOMER",
        "appdynamics/appdynamics-mcp-server:latest"
      ],
      "env": {
        "APPD_ENVIRONMENT": "https://your-controller.example.com/controller",
        "APPD_CLIENT_ID": "<API-client-name>",
        "APPD_CLIENT_SECRET": "<API-client-secret>",
        "APPD_CUSTOMER": "<AppDynamics-account-name>"
      }
    }
  }
}

Codex TOML configuration

Set the API Client values in the environment that starts Codex:

BASH
export APPD_ENVIRONMENT="https://your-controller.example.com/controller"
export APPD_CLIENT_ID="<API-client-name>"
export APPD_CLIENT_SECRET="<API-client-secret>"
export APPD_CUSTOMER="<AppDynamics-account-name>"

Add the server to ~/.codex/config.toml:

TOML
[mcp_servers.appdynamics]
command = "docker"
args = [
  "run", "--rm", "-i",
  "--env", "MCP_TRANSPORT=stdio",
  "--env", "APPD_AUTH_MODE=oauth",
  "--env", "APPD_ENVIRONMENT",
  "--env", "APPD_CLIENT_ID",
  "--env", "APPD_CLIENT_SECRET",
  "--env", "APPD_CUSTOMER",
  "appdynamics/appdynamics-mcp-server:latest"
]
env_vars = [
  "APPD_ENVIRONMENT",
  "APPD_CLIENT_ID",
  "APPD_CLIENT_SECRET",
  "APPD_CUSTOMER"
]

Optional Analytics Events access for stdio

For either stdio authentication mode, also supply these values when live Analytics Events access is required:

CODE
APPD_ANALYTICS_EVENTS_URL
APPD_ANALYTICS_EVENTS_GLOBAL_ACCOUNT_NAME
EVENTS_API_KEY

Forward all three variables through the Docker --env arguments and the client environment configuration. EVENTS_API_KEY is independent of the Controller bearer token or OAuth credentials.

The Codex examples follow the official OpenAI MCP configuration options for stdio environment forwarding and HTTP bearer and header configuration.

Verify the connection

Ask your AI assistant with this query.
CODE
List all APM applications monitored in AppDynamics.

Verify that your AI assistant calls this list_apm_applications tool and displays the application list.

Access multiple Controllers with stdio

Register a separate named stdio MCP server for each Controller that you want to access from one MCP client.

Each stdio MCP server process has its own Controller URL, credentials, optional Analytics Events configuration, and caches. This configuration follows the stdio client configuration.

  1. Create an environment file for each Controller.

    For example, create controller-a.env with the following content:

    BASH
    MCP_TRANSPORT=stdio
    APPD_AUTH_MODE=env_bearer
    APPD_ENVIRONMENT=https://controller-a.example.com/controller
    APPD_API_TOKEN=<controller-a-token>
    # Optional Analytics Events
    APPD_ANALYTICS_EVENTS_URL=<analytics-url>
    APPD_ANALYTICS_EVENTS_GLOBAL_ACCOUNT_NAME=<controller-a-global-account-name>
    EVENTS_API_KEY=<controller-a-events-key>

    Create controller-b.env with the values for Controller B.

    To use OAuth, replace APPD_API_TOKEN with the following settings:

    BASH
    APPD_AUTH_MODE=oauth
    APPD_CLIENT_ID=<api-client-name>
    APPD_CLIENT_SECRET=<api-client-secret>
    APPD_CUSTOMER=<account-name>
  2. Register both Controllers in Codex.
    TOML
    [mcp_servers.appdynamics_controller_a]
    command = "docker"
    args = [
      "run", "--rm", "-i",
      "--env-file", "/secure/path/controller-a.env",
      "appdynamics/appdynamics-mcp-server:latest"
    ]
    [mcp_servers.appdynamics_controller_b]
    command = "docker"
    args = [
      "run", "--rm", "-i",
      "--env-file", "/secure/path/controller-b.env",
      "appdynamics/appdynamics-mcp-server:latest"
    ]

Each named entry connects to one Controller and maintains independent credentials and caches. You can access multiple Controllers from one MCP client.