PingOne AIC

You can run and use the PingOne Advanced Identity Cloud MCP Server to let AI assistants securely interact with PingOne AIC environments. It supports managing users, roles, groups, organizations, themes, and logs from conversational AI, while providing auditable, user-based actions and flexible deployment options.

How to use

Use this MCP server to perform CRUD operations on managed objects, manage authentication themes, query logs, and handle environment variables from your AI assistant. You authenticate once per session, and subsequent tool calls reuse your token. In Docker deployments, tokens are stored ephemeral to the container for increased security. All actions are tied to the authenticated user for traceability.

How to install

Prerequisites: install Node.js 18+ and have access to a PingOne Advanced Identity Cloud Sandbox or Development Tenant.

Step 1: Install and build from source (local development)

# Clone the repository
git clone https://github.com/pingidentity/aic-mcp-server.git
cd aic-mcp-server

# Install dependencies
npm install

# Compile TypeScript
npm run build

Step 2: Run the local build with your MCP client configured to point to your AIC tenant

{
  "mcpServers": {
    "aic-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/aic-mcp-server/dist/index.js"],
      "env": {
        "AIC_BASE_URL": "your-tenant.forgeblocks.com"
      }
    }
  }
}

Docker Deployment

⚠️ EXPERIMENTAL: Docker deployment uses OAuth 2.0 Device Code Flow with MCP form elicitation. If your client doesn’t support form elicitation, use the local deployment method above.

Build the Docker image and run the container with the AIC_BASE_URL configured in the container environment.

# Build the Docker image
npm run docker:build

# Run the container with the required base URL
# Example using Claude/Desktop/Cursor style config
docker run --rm -i -e AIC_BASE_URL=your-tenant.forgeblocks.com pingidentity/aic-mcp-server:latest

Configuration and environment variables

Configure your MCP client to point to your PingOne AIC base URL. The standard configuration uses astdio mode with npx to run the MCP server and passes the AIC_BASE_URL as an environment variable.

{
  "mcpServers": {
    "aic-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ping-identity/aic-mcp-server"],
      "env": {
        "AIC_BASE_URL": "your-tenant.forgeblocks.com"
      }
    }
  }
}

Security and authentication overview

The MCP server authenticates users using OAuth 2.0 PKCE for local deployment and a Device Code Flow for containerized deployment. All actions are user-based and auditable, with tokens stored securely or ephemeral depending on deployment mode.

Troubleshooting

If you encounter issues starting the MCP client or authenticating, verify that the AIC_BASE_URL is correctly set and that the MCP client has permission to open a browser for login during the first tool use.

Common issues include environment variable misconfigurations, port conflicts for OAuth redirects, and unsupported client forms in container environments.

Development and testing

You can run the full test suite, build, and inspect tools during local development. See the commands for testing and type checks in the development flow.

Notes on usage with tools and UI

When you start using tools for the first time in a session, your browser will open to the PingOne AIC login page. After authentication, you can run CRUD operations, theme management, and log queries through your AI tools.

Contributing

Contributions are welcome. Share enhancements or fixes via your preferred contribution workflow.

License

The component is provided under the Apache 2.0 license.

Available tools

listManagedObjects

Discover all managed object types in your environment and prepare for subsequent CRUD operations.

getManagedObjectSchema

Retrieve the schema definition for a specific managed object type to understand required fields and structure.

queryManagedObjects

Query objects with filters, pagination, and sorting to locate specific items quickly.

getManagedObject

Retrieve the complete profile of a single managed object by its identifier.

createManagedObject

Create a new managed object with the required properties for your environment.

patchManagedObject

Update fields on an existing managed object to reflect changes.

deleteManagedObject

Remove a managed object from your environment when it is no longer needed.

getThemeSchema

Obtain the full theme schema to customize login and account pages.

getThemes

List all themes available in a realm or environment.

getTheme

Retrieve a theme’s complete configuration.

createTheme

Create a new theme with customized branding.

updateTheme

Modify properties of an existing theme.

deleteTheme

Delete a theme from the environment.

setDefaultTheme

Set a theme as the default for the realm or environment.

getLogSources

List all available sources of authentication and activity logs.

queryLogs

Query logs with time ranges, sources, and content filters to analyze activity.

queryESVs

Query environment secrets and variables by ID or pattern.

getVariable

Retrieve a variable with its decoded value.

setVariable

Create or update an environment variable or secret.

deleteVariable

Delete an environment variable or secret.