PingOne Advanced Identity Cloud MCP Server

Features • Use Cases • Prerequisites • Getting Started • Authentication • Available Tools • Agent Skills • Docker Deployment • Security • Monitoring & Audit • Troubleshooting • Development • License

An MCP (Model Context Protocol) server that enables AI assistants to interact with PingOne Advanced Identity Cloud environments. Manage users, roles, groups, organizations, customize authentication themes, analyze logs, and query identity data directly from your AI conversations.

Ask questions like "Find all alpha_users with email starting with john@example.com", "Create a new theme called 'Corporate Brand' with primary color #0066cc", or "Show me all ERROR level logs from the am-authentication source in the last hour".

Features

• Administer your AIC environment using natural language - Interact with PingOne AIC from whichever AI tool you use daily. No need to switch to the admin console or write API scripts - just ask your AI assistant.

• Secure authentication - Supports OAuth 2.0 PKCE flow for local deployment and Device Code Flow for containerized deployment. All actions are user-based and auditable. Tokens stored securely in OS keychain (local) or ephemerally (Docker).

• Broad tool support - Supports full CRUD operations against any managed object type in your environment (users, roles, groups, organizations, and custom types), authentication journey and script management, theme customization, advanced log querying, and environment variable configuration.

Use Cases

• Journey Management - "Show me the Login journey", "Create a new MFA journey", "Add a scripted decision node to the registration flow", "Set Login as the default journey"

• Authentication Customization - "Create a branded theme with our corporate colors", "Show me all themes in production", "Set the new theme as default"

• Audit & Monitoring - "Show me failed login attempts in the last hour", "Find all logs for transaction abc-123", "What log sources are available?"

• Identity Operations - "Find all users with admin in their username", "Create a new developer role", "Update the email for user xyz123"

• Configuration Management - "List all environment variables", "Create a new API key variable", "Update the database connection string"

Getting Started

Prerequisites

• Node.js 18+

• PingOne Advanced Identity Cloud Sandbox or Development Tenant

• MCP-compatible client (Claude Code, Claude Desktop, Cursor, VS Code with GitHub Copilot, Gemini CLI, Codex, etc.)

Configure Your MCP Client

The MCP server requires the AIC_BASE_URL environment variable to be set to your PingOne AIC hostname.

Add this to your MCP client configuration:

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

Required: Replace your-tenant.forgeblocks.com with your PingOne AIC tenant URL.

Client-specific instructions:

Add this to your Claude MCP configuration (claude.json for Claude Code or claude_desktop_config.json for Claude Desktop):

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

Add this to your Cursor MCP configuration (.cursor/mcp.json):

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

Add this to your Copilot MCP configuration (mcp.json):

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

Add this to your Gemini CLI MCP configuration (settings.json):

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

Add this to your Codex MCP configuration (~/.codex/config.toml):

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

Restart your MCP client and start asking questions! Your browser will open for authentication when you use the first tool in a session.

Authentication

The server uses OAuth 2.0 PKCE flow for secure user authentication:

1. First Tool Use - Browser opens automatically for user login at PingOne AIC when you use a tool for the first time in a session

2. Token Storage - Access tokens stored securely in OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)

3. Automatic Reuse - Cached tokens used for subsequent tool calls within the same session

4. Auto Re-authentication - When tokens expire during a session, browser opens again for new login

Docker Deployment: Uses OAuth 2.0 Device Code Flow with ephemeral token storage (tokens deleted on container restart).

Security Features:

• User-based actions provide complete audit trail

• All actions traceable to authenticated users for compliance

Available Tools

The server provides tools for AI agents to interact with your PingOne AIC environment:

Managed Objects

Generic CRUD operations for any managed object type in your environment, plus administrative tools for managing object type definitions and relationship properties.

Themes

Customize login and account page appearance.

Logging

Query and analyze authentication and activity logs.

ESVs (Environment Secrets and Variables)

Manage environment secrets and variables.

Feature Management

Inspect and enable optional features in PingOne AIC. A single listFeatures tool returns a unified view of all IDM and AIC platform features with install status. Install operations are one-way and cannot be undone from these tools.

Applications (Not available when using Docker)

**📍 Not available when using MCP from a Docker container **: Application tools are automatically excluded in Docker deployments because they require browser-based PKCE authentication which is incompatible with the Device Code Flow used in containers.

Manage OIDC applications in a realm.

AM Journeys (Not available when using Docker)

**📍 Not available when using MCP from a Docker container **: AM Journey tools are automatically excluded in Docker deployments because they require browser-based PKCE authentication which is incompatible with the Device Code Flow used in containers.

Manage authentication journeys, node types, and scripts.

Key Feature: The getJourney tool automatically fetches and includes all node schemas and configurations in parallel, so you get complete journey details in a single call - no need to manually fetch node information.

Agent Skills

This repository ships agent skills that extend your AI assistant's ability to work with the AIC MCP server. Once installed, your agent can take on operational tasks — like auditing MCP usage in your environment — without needing explicit instructions.

Install the Skills

Option 1 — Skills CLI (works with any supported agent):

npx skills add pingidentity/aic-mcp-server

Option 2 — Manual installation:

Clone the repository and copy the skills from .claude/skills/ to your agent's skills directory. See your agent's documentation for the correct location:

• Claude Code

• VS Code / GitHub Copilot

• Gemini CLI

• Codex

• Goose

Once installed, verify by asking your agent "What skills do you have?" — you should see monitor-usage in the list.

Docker Deployment

⚠️ EXPERIMENTAL: Docker deployment uses OAuth 2.0 Device Code Flow with MCP form elicitation. This requires MCP client support for form elicitation, which is currently limited. If your client doesn't support it, use the local deployment method above.

Build Image

npm run docker:build

Configure Your MCP Client

Claude Code or Claude Desktop

Add this to your Claude MCP configuration (claude.json for Claude Code or claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "aic-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "AIC_BASE_URL=your-tenant.forgeblocks.com",
        "pingidentity/aic-mcp-server:latest"
      ]
    }
  }
}

Authentication: When authentication is required, your MCP client should display a URL. Click it to authenticate in your browser, then accept the prompt in your client.

Token Storage: Tokens are stored ephemerally in the container filesystem (/app/tokens/token.json) and deleted on container restart for enhanced security.

Security

The PingOne AIC MCP Server implements multiple security layers:

• Secure credential storage - Tokens stored in OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) for local deployment, or ephemerally in container filesystem for Docker

• No plain text secrets - No sensitive information stored in configuration files

• OAuth 2.0 authentication - PKCE flow for local deployment prevents authorization code interception; Device Code flow for containerized deployment

• User-based authentication - All API calls are authenticated as the user who logged in, providing complete audit trails

• Input validation - Built-in protections against path traversal and query injection attacks

• Tenant isolation - Tokens are validated against the configured AIC_BASE_URL to prevent accidental cross-tenant operations

Monitoring & Audit

All operations performed through the MCP server are executed as the authenticated user — there are no anonymous or service-account-attributed actions. Every tool invocation produces a full audit trail in the AIC audit logs, attributable to the individual who authenticated the session.

Authentication events

The server authenticates using two registered OAuth 2.0 clients:

• AICMCPClient — used for the initial user login (PKCE or Device Code flow)

• AICMCPExchangeClient — used to obtain scoped tokens for each tool call via RFC 8693 token exchange

Filtering the am-authentication log source for either of these client IDs will surface all MCP authentication activity. Each token exchange references the original user login, providing a complete chain from the tool call back to the authenticated identity.

Attributing actions to a user

All API calls made by the server carry the scoped token issued to the authenticated user. Configuration changes (journeys, scripts, OIDC apps) appear in AM audit logs and identity operations (managed objects, groups, relationships) appear in IDM audit logs — all attributed to the user identity, not a service account.

Identifying MCP traffic

All requests from the server include a User-Agent header of the form aic-mcp-server/<version>. This can be used to filter access logs and isolate MCP-originated traffic from browser sessions, automated reconciliation jobs, and other API clients.

"FATAL: AIC_BASE_URL environment variable is not set"

Set the AIC_BASE_URL environment variable in your MCP client configuration to your PingOne AIC tenant URL (e.g., your-tenant.forgeblocks.com or https://your-tenant.forgeblocks.com).

"Port 3000 is already in use"

Another service is using port 3000 (required for OAuth redirect). Stop that service and try again.

"Browser doesn't open during authentication"

Check that the open package has permissions to launch your browser, or manually navigate to the URL shown in the error message.

Docker: "URL not displayed during authentication"

Your MCP client may not support form elicitation yet. Use the local deployment method instead.

Development

To build the server from source for 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

Then configure your MCP client to use the local build:

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

For type checking without building:

npm run typecheck

The project includes a comprehensive test suite covering all tools and authentication flows.

# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

# Update tool schema snapshots
npm run test:snapshots:update

Use the MCP Inspector to visually test tools in a web interface:

# Development mode (no build required - faster iteration)
AIC_BASE_URL=your-tenant.forgeblocks.com npm run dev:inspect

# Production mode (requires build first)
npm run build
AIC_BASE_URL=your-tenant.forgeblocks.com npm run inspect

Hosts a web interface for interactive tool testing and OAuth flow debugging.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Feedback & Issues

We welcome your feedback! Please use this repository's issue tracker to submit feedback, bug reports, or enhancement requests. For existing issues, you can add a 👍 reaction to help our team gauge priority.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.