The PingOne MCP (Model Context Protocol) server enables AI assistants to review and manage PingOne tenants by integrating the PingOne management API to AI assistant conversations.
Caution
Preview Software Notice
This is preview software provided AS IS with no warranties of any kind.
- Functionality, features, and APIs are subject to change at any time without prior notice
- Use against production environments or mission-critical workloads is not advised
- Limited support is available during the public preview phase — please report bugs and provide feedback via the GitHub issue tracker
Your use of this software constitutes acceptance of these terms.
Caution
Security Notice
Depending on the requests made to the MCP server, tenant configuration or data may be returned. Do not use the MCP server with untrusted MCP clients, agent code or LLM inference and ensure least privilege principles are followed when granting role permissions to MCP server users.
Warning
Review Generated Configuration
Configuration can be generated dynamically using LLM and user feedback represented dynamically back to agents/conversations. Be sure to review generated configuration before promoting to production environments, or those serving live identity/access requests.
-
Administer your PingOne environment using natural language - Interact with PingOne from whichever AI IDE or MCP client tool you use daily.
-
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).
-
Environment, application and population operations - Provides tool integrations to create, update and analyze configurations for tenant activities.
This MCP server is designed to help developers integrate PingOne capabilities into their applications, while also helping tenant administrators monitor and troubleshoot issues. Common use cases include:
- Accelerate application development
- Generate sample applications
- Monitor tenants and environment configuration
Have you got an interesting use case or project you'd like to share with the community? We'd love to hear about it on the PingOne Community pages!
- A licensed or trial PingOne cloud subscription. - Don't have a tenant? Sign up for a free trial here.
- MCP-compatible client (E.g. Claude Desktop, VS Code Copilot Chat, Cursor, Zed, etc.)
- Homebrew (for macOS and Linux package install)
The MCP server requires a worker application in your PingOne tenant to access the management APIs. You'll need to capture two values during setup:
- Environment ID - The PingOne environment containing your worker application (referred to later as
{{admin environment id}}) - Client ID - The worker application's client identifier (referred to later as
{{mcp application client id}})
The server uses the Authorization Code grant with PKCE by default. Configure your worker application with:
- Grant Type: Authorization Code with PKCE required
- Response Type: Code
- Token Endpoint Authentication: None
- Redirect URI:
http://127.0.0.1:7464/callback - Application Roles: None required (the MCP server inherits roles from the authenticated user)
Note: For detailed instructions on creating the application and setting up admin users, see Setting Up PingOne Worker Applications.
Alternative: Device Authorization Grant (for headless/containerized environments)
For headless or containerized environments, use the Device Authorization grant. Configure your worker application with:
- Grant Type: Device Authorization
- Token Endpoint Authentication: None
- Redirect URI:
http://127.0.0.1:7464/callback - Application Roles: None required (the MCP server inherits roles from the authenticated user)
This grant type is ideal for environments without a browser, such as CI/CD pipelines or remote servers.
Use Ping Identity's Homebrew tap to install the PingOne MCP server
brew tap pingidentity/tap
brew install pingone-mcp-serverAlternatively, expand the instructions below to install manually from GitHub release artifacts.
macOS - GitHub Release Manual Installation Instructions
See the latest GitHub release for artifact downloads, artifact signatures, and the checksum file. To verify package downloads, see the Verify Section.
OR
Use the following single-line command to install the server into '/usr/local/bin' directly.
RELEASE_VERSION=$(basename $(curl -Ls -o /dev/null -w %{url_effective} https://github.com/pingidentity/pingone-mcp-server/releases/latest)); \
OS_NAME=$(uname -s); \
HARDWARE_PLATFORM=$(uname -m | sed s/aarch64/arm64/ | sed s/x86_64/amd64/); \
URL="https://github.com/pingidentity/pingone-mcp-server/releases/download/${RELEASE_VERSION}/pingone-mcp-server_${RELEASE_VERSION#v}_${OS_NAME}_${HARDWARE_PLATFORM}"; \
curl -Ls -o pingone-mcp-server "${URL}"; \
chmod +x pingone-mcp-server; \
sudo mv pingone-mcp-server /usr/local/bin/pingone-mcp-server;See the latest GitHub release for the checksums.txt file. The checksums are in the format of SHA256.
Linux - GitHub Release Manual Installation Instructions
See the latest GitHub release for artifact downloads, artifact signatures, and the checksum file. To verify package downloads, see the Verify Section.
OR
Use the following single-line command to install the server into '/usr/local/bin' directly.
RELEASE_VERSION=$(basename $(curl -Ls -o /dev/null -w %{url_effective} https://github.com/pingidentity/pingone-mcp-server/releases/latest)); \
OS_NAME=$(uname -s); \
HARDWARE_PLATFORM=$(uname -m | sed s/aarch64/arm64/ | sed s/x86_64/amd64/); \
URL="https://github.com/pingidentity/pingone-mcp-server/releases/download/${RELEASE_VERSION}/pingone-mcp-server_${RELEASE_VERSION#v}_${OS_NAME}_${HARDWARE_PLATFORM}"; \
curl -Ls -o pingone-mcp-server "${URL}"; \
chmod +x pingone-mcp-server; \
sudo mv pingone-mcp-server /usr/local/bin/pingone-mcp-server;See the latest GitHub release for the checksums.txt file. The checksums are in the format of SHA256.
Test the installation:
pingone-mcp-server --versionFor quick installation, use one of the install buttons above.
To add the MCP server configuration manually, add the following configuration to your MCP configuration file:
{
"servers": {
"pingOne": {
"type": "stdio",
"command": "pingone-mcp-server",
"args": [
"run",
],
"env": {
"PINGONE_MCP_ENVIRONMENT_ID": "${input:pingone_environment_id}",
"PINGONE_AUTHORIZATION_CODE_CLIENT_ID": "${input:pingone_mcp_client_id}",
"PINGONE_ROOT_DOMAIN": "${input:pingone_api_root_domain}",
},
},
},
"inputs": [
{
"type": "promptString",
"id": "pingone_environment_id",
"description": "The environment ID containing the MCP server worker application",
"password": false
},
{
"type": "promptString",
"id": "pingone_mcp_client_id",
"description": "The client ID of the MCP server worker application",
"password": false
},
{
"type": "promptString",
"id": "pingone_api_root_domain",
"description": "The root domain of your PingOne tenant (e.g., `pingone.com` , `pingone.eu` , `pingone.ca`)",
"password": false
}
]
}Once installed, ensure agent mode is turned on and the MCP server has started, then make the first request!
Alternative: Using the Device Authorization Grant
To configure the MCP server to use the Device Authorization grant type, add the --grant-type command argument with a value of device_code and add the environment variables PINGONE_DEVICE_CODE_CLIENT_ID and PINGONE_DEVICE_CODE_SCOPES as shown in the example:
{
"servers": {
"pingOne": {
"type": "stdio",
"command": "pingone-mcp-server",
"args": [
"run",
"--grant-type",
"device_code"
],
"env": {
"PINGONE_MCP_ENVIRONMENT_ID": "${input:pingone_environment_id}",
"PINGONE_DEVICE_CODE_CLIENT_ID": "${input:pingone_mcp_client_id}",
"PINGONE_DEVICE_CODE_SCOPES": "openid",
"PINGONE_ROOT_DOMAIN": "${input:pingone_api_root_domain}",
},
},
},
"inputs": [
{
"type": "promptString",
"id": "pingone_environment_id",
"description": "The environment ID containing the MCP server worker application",
"password": false
},
{
"type": "promptString",
"id": "pingone_mcp_client_id",
"description": "The client ID of the MCP server worker application",
"password": false
},
{
"type": "promptString",
"id": "pingone_api_root_domain",
"description": "The root domain of your PingOne tenant (e.g., `pingone.com` , `pingone.eu` , `pingone.ca`)",
"password": false
}
]
}To add the MCP server configuration manually, add the following configuration to your Claude Desktop config (claude_desktop_config.json) or via Settings -> Developer -> Local MCP Servers:
{
"mcpServers": {
"pingone": {
"type": "stdio",
"command": "pingone-mcp-server",
"args": [
"run"
],
"env": {
"PINGONE_MCP_ENVIRONMENT_ID": "<<paste worker application environment UUID {{admin environment id}} here>>",
"PINGONE_AUTHORIZATION_CODE_CLIENT_ID": "<<paste worker application client ID UUID {{mcp application client id}} here>>",
"PINGONE_ROOT_DOMAIN": "<<paste root domain of your PingOne tenant here (e.g., pingone.com)>>"
}
}
}
}If you've downloaded the binary manually to a location not on the PATH, change the command to refer to the full path to the binary file.
Alternative: Using the Device Authorization Grant
To configure the MCP server to use the Device Authorization grant type, add the --grant-type command argument with a value of device_code and add the environment variables PINGONE_DEVICE_CODE_CLIENT_ID and PINGONE_DEVICE_CODE_SCOPES as shown in the example:
{
"mcpServers": {
"pingOne": {
"type": "stdio",
"command": "pingone-mcp-server",
"args": [
"run",
"--grant-type",
"device_code"
],
"env": {
"PINGONE_MCP_ENVIRONMENT_ID": "<<paste worker application environment UUID {{admin environment id}} here>>",
"PINGONE_DEVICE_CODE_CLIENT_ID": "<<paste worker application client ID UUID {{mcp application client id}} here>>",
"PINGONE_DEVICE_CODE_SCOPES": "openid",
"PINGONE_ROOT_DOMAIN": "<<paste root domain of your PingOne tenant here (e.g., pingone.com)>>"
}
}
}
}To install the MCP server in Claude code, run the following commands, changing the PINGONE_MCP_ENVIRONMENT_ID, PINGONE_AUTHORIZATION_CODE_CLIENT_ID and PINGONE_ROOT_DOMAIN environment variables for your tenant.
export PINGONE_MCP_ENVIRONMENT_ID="<<paste worker application environment UUID {{admin environment id}} here>>"
export PINGONE_AUTHORIZATION_CODE_CLIENT_ID="<<paste worker application client ID UUID {{mcp application client id}} here>>"
export PINGONE_ROOT_DOMAIN="<<paste root domain of your PingOne tenant here (e.g., pingone.com)>>"claude mcp add --transport stdio pingOne \
--env PINGONE_MCP_ENVIRONMENT_ID=$PINGONE_MCP_ENVIRONMENT_ID \
--env PINGONE_AUTHORIZATION_CODE_CLIENT_ID=$PINGONE_AUTHORIZATION_CODE_CLIENT_ID \
--env PINGONE_ROOT_DOMAIN=$PINGONE_ROOT_DOMAIN \
-- pingone-mcp-server runCheck the MCP server has been loaded correctly:
claude mcp listChecking MCP server health...
pingOne: pingone-mcp-server run - ✓ ConnectedFor quick installation, the install button above.
Be sure to change the PINGONE_MCP_ENVIRONMENT_ID, PINGONE_AUTHORIZATION_CODE_CLIENT_ID and PINGONE_ROOT_DOMAIN environment variables for your tenant.
To add the MCP server configuration manually, add the following configuration to your Cursor config (~/.cursor/mcp.json) or via Settings -> Cursor Settings -> Tools & MCP:
{
"mcpServers": {
"pingOne": {
"type": "stdio",
"command": "pingone-mcp-server",
"args": [
"run"
],
"env": {
"PINGONE_MCP_ENVIRONMENT_ID": "<<paste worker application environment UUID {{admin environment id}} here>>",
"PINGONE_AUTHORIZATION_CODE_CLIENT_ID": "<<paste worker application client ID UUID {{mcp application client id}} here>>",
"PINGONE_ROOT_DOMAIN": "<<paste root domain of your PingOne tenant here (e.g., pingone.com)>>"
}
}
}
}Alternative: Using the Device Authorization Grant
To configure the MCP server to use the Device Authorization grant type, add the --grant-type command argument with a value of device_code and add the environment variables PINGONE_DEVICE_CODE_CLIENT_ID and PINGONE_DEVICE_CODE_SCOPES as shown in the example:
{
"mcpServers": {
"pingOne": {
"type": "stdio",
"command": "pingone-mcp-server",
"args": [
"run",
"--grant-type",
"device_code"
],
"env": {
"PINGONE_MCP_ENVIRONMENT_ID": "<<paste worker application environment UUID {{admin environment id}} here>>",
"PINGONE_DEVICE_CODE_CLIENT_ID": "<<paste worker application client ID UUID {{mcp application client id}} here>>",
"PINGONE_DEVICE_CODE_SCOPES": "openid",
"PINGONE_ROOT_DOMAIN": "<<paste root domain of your PingOne tenant here (e.g., pingone.com)>>"
}
}
}
}If you'd like to build and run the project from source, use make build which will compile the code to a binary at ./bin/pingone-mcp-server.
When configuring MCP clients, ensure that the command value refers to the full path up to the built binary. For example:
{
"servers": {
"pingOne": {
"type": "stdio",
"command": "/path/to/cloned_projects/pingone-mcp-server/bin/pingone-mcp-server",
"args": [
"run",
],
"env": {
"PINGONE_MCP_DEBUG": "true",
"PINGONE_MCP_ENVIRONMENT_ID": "<<paste worker application environment UUID {{admin environment id}} here>>",
"PINGONE_AUTHORIZATION_CODE_CLIENT_ID": "<<paste worker application client ID UUID {{mcp application client id}} here>>",
"PINGONE_ROOT_DOMAIN": "<<paste root domain of your PingOne tenant here (e.g., pingone.com)>>",
},
},
}
}The server uses OAuth 2.0 Authorization Code flow with PKCE for secure administrator authentication by default. The server can be configured to use the Device Authorization grant type (also using PKCE) as an optional feature.
- First Tool Use - Browser opens automatically for administrator login to your configured PingOne tenant when you use a tool for the first time in a session
- Token Storage - Access tokens stored securely in OS keychain where available (macOS Keychain, Windows Credential Manager, Linux Secret Service)
- Automatic Reuse - Cached tokens used for subsequent tool calls within the same session
- Auto Re-authentication - When tokens expire during a session, browser opens again for new login
Important
Restrictions for Production Environments
By default, any tool that has the capability of writing both configuration and/or data, or any tool that can read production data are restricted for use on environments that are of type PRODUCTION. This is to safeguard against unintended access to sensitive data or accidental configuration changes to live systems.
Important
Read Only by Default
By default the server starts in "Read Only" mode, to protect against accidental changes. To enable write tools, add the --disable-read-only command line argument. For more information, see Enabling Write Tools.
The MCP server provides a set of tools to interact with PingOne environments. Tools are organized into tool collections, that allow groups of tools to be enabled and disabled globally when the server starts.
Enabling/disabling tools (or collections of tools) provides the user control over which tools are made available to the MCP client at runtime, which can both reduce the number of unneeded tools for the agent (reducing tool and context bloat) but can also provide a backstop measure against accidental changes to unrelated configurations in the environment.
By default, the server starts in read-only mode, which only exposes tools that retrieve information without modifying any configuration or data. This provides a safety layer against accidental changes.
To enable write operations (create, update, delete), add the --disable-read-only flag when starting the server:
pingone-mcp-server run --disable-read-onlyOr in your MCP client configuration:
{
"servers": {
"pingOne": {
"type": "stdio",
"command": "pingone-mcp-server",
"args": ["run", "--disable-read-only"],
"env": {
"PINGONE_MCP_ENVIRONMENT_ID": "your-env-id",
"PINGONE_AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
"PINGONE_ROOT_DOMAIN": "pingone.com"
}
}
}
}Warning
Important Behavior: If you explicitly include specific tools/collections that are capable of writing configuration to the PingOne tenant, you must also use --disable-read-only to make those write tools available to the MCP client.
You can fine-tune which tools are available using inclusion and exclusion flags. These flags accept comma-separated lists of tool names or collection names.
--include-tools- Enable only specified tools--exclude-tools- Disable specified tools--include-tool-collections- Enable only specified collections--exclude-tool-collections- Disable specified collections--disable-read-only- Include write tools (required for create/update/delete operations)
Priority Rules:
- Exclusions take priority - If a tool appears in both include and exclude lists, it will be excluded
- Empty inclusion lists allow all - If no
--include-*flags are specified, all tools/collections are included by default (subject to read-only filter and exclusions) - Read-only filter applies to tools - The
--disable-read-onlyflag must be set to include any write tools, even if explicitly included
Note
Conflicting Arguments: If you specify write tools in --include-tools without adding --disable-read-only, the server will log a warning message listing which write tools will be excluded, along with a suggestion to add the flag.
Examples:
Enable only read tools from specific collections:
pingone-mcp-server run \
--include-tool-collections applications,environmentsThis enables list_applications, get_application, list_environments, get_environment, and get_environment_services but excludes all write tools.
Enable all tools including writes from specific collections:
pingone-mcp-server run \
--disable-read-only \
--include-tool-collections applications,environmentsThis enables all application and environment tools including create, update operations.
Enable everything except specific collections:
pingone-mcp-server run \
--disable-read-only \
--exclude-tool-collections populationsThis enables all tools across all collections except the populations collection.
Enable specific tools only:
pingone-mcp-server run \
--include-tools list_applications,get_application,list_environmentsThis enables only the three specified read-only tools.
Enable specific write tools (requires --disable-read-only):
pingone-mcp-server run \
--disable-read-only \
--include-tools create_oidc_application,update_oidc_applicationThis enables only the two application write tools.
Complex filtering - include collection but exclude specific tools:
pingone-mcp-server run \
--disable-read-only \
--include-tool-collections applications \
--exclude-tools update_oidc_applicationThis enables all application tools except update_oidc_application.
Caution
Known Limitation: When using --include-tools with write tool names but forgetting --disable-read-only, the tools will be silently excluded. Always remember to add --disable-read-only when you intend to enable write operations.
Tip
Best Practice: Start with read-only mode and specific collections, then gradually enable write tools as needed. This reduces cognitive load for AI agents and minimizes risk of unintended changes.
Tool collections group related tools together for easier management. Each collection corresponds to a PingOne resource type.
| Collection | Description | Tools Included |
|---|---|---|
applications |
Manage OIDC/OAuth 2.0 applications in PingOne environments | list_applications, get_application, create_oidc_application, update_oidc_application |
environments |
Manage PingOne environments and their service configurations | list_environments, get_environment, create_environment, update_environment, get_environment_services, update_environment_services |
populations |
Manage user populations within PingOne environments | list_populations, get_population, create_population, update_population |
The server provides tools for AI agents to interact with your PingOne environment:
Create, update, view applications within an environment.
| Tool | Collections | Read Only | Description | Usage Examples |
|---|---|---|---|---|
create_oidc_application |
applications |
Create an OpenID Connect/OAuth 2.0 application | - Create an OIDC app called "My Web App" - Create an application using PKCE with redirect URI https://myapp-dev.bxretail.org/callback |
|
get_application |
applications |
✓ | Retrieve the detailed configuration of an application | - Show me application abc-123 - Get the config for My Web App - Display the OIDC settings for app xyz |
list_applications |
applications |
✓ | List applications accessible to the authenticated user, each with a basic configuration summary, within an environment | - Show all applications in environment xyz - List OIDC apps - What applications exist and are enabled? |
update_oidc_application |
applications |
Update an OpenID Connect/OAuth 2.0 application's configuration | - Update app xyz to add a new redirect URI - Change the token lifetime for My Web App - Modify the grant types for application abc-123 - Disable application abc-123 |
Manage PingOne environments and their services.
| Tool | Collections | Read Only | Description | Usage Examples |
|---|---|---|---|---|
create_environment |
environments |
Create a new sandbox PingOne environment | - Create an environment called Dev - Add a new environment in the NA region - Create a test environment for our team |
|
get_environment |
environments |
✓ | Retrieve an environment's full configuration | - Show me environment abc-123 - Get the config for Dev environment - Display environment xyz details |
list_environments |
environments |
✓ | List all PingOne environments accessible to the authenticated user | - Show all environments - List active environments - Find environments starting with "Prod" |
update_environment |
environments |
Update environment configuration | - Rename environment to Testing - Change description of Dev environment |
|
get_environment_services |
environments |
✓ | Retrieve all PingOne shared services assigned to a specified environment | - What services are enabled in environment xyz? - Show me the bill of materials - List services for Dev environment - Are MFA and Neo enabled on environment abc-123 |
update_environment_services |
environments |
Update the services assigned to an environment | - Enable DaVinci in environment xyz - Add PingOne Verify service - Update the environment abc-123 services to include MFA |
Manage user populations within environments.
| Tool | Collections | Read Only | Description | Usage Examples |
|---|---|---|---|---|
create_population |
populations |
Create a population in an environment | - Create a population called External Users - Add population for employees - Create Customers population with French language |
|
get_population |
populations |
✓ | Retrieve population configuration by ID | - Show me population abc-123 - Get the External Users population config - Display population xyz details |
list_populations |
populations |
✓ | List populations in an environment | - Show all populations in environment xyz - List populations - Find populations starting with "External" |
update_population |
populations |
Update population configuration | - Change population description - Update External Users to use new password policy - Modify preferred language for population xyz |
The PingOne 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
Having issues with the MCP server? Check the comprehensive Troubleshooting Guide for solutions to common problems including:
- Authentication and permission errors
- Configuration issues
- Tool execution problems
- MCP client integration issues
- Debug mode and logging
For quick debugging, enable debug mode by setting PINGONE_MCP_DEBUG=true in your environment variables. See the troubleshooting guide for details.
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.
We welcome pull requests for:
- Repository management (e.g., scripts, GitHub Actions)
- Documentation updates
- Code contributions to advance the project such as adding new tools or collections. For larger or more structural changes, please raise an issue on the project as a proposal first so the project team can provide guidance.
Please see our contributing guide for more information.