pingidentity/pingone-mcp-server

PingOne MCP Server

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.

Features

• 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.

Use Cases

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!

Getting Started

Prerequisites

• 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)

Prepare PingOne for MCP Server Use

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}})

Default: Authorization Code with PKCE

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 .

Install the MCP Server

macOS and Linux

Use Ping Identity's Homebrew tap to install the PingOne MCP server

brew tap pingidentity/tap
brew install pingone-mcp-server

Alternatively, expand the instructions below to install manually from GitHub release artifacts.

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;

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;

Test the installation:

pingone-mcp-server --version

Use with VS Code

For 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!

{
  "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
    }
  ]
}

Use with Claude Desktop

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.

{
  "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)>>"
      }
    }
  }
}

Use with Claude Code

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 run

Check the MCP server has been loaded correctly:

claude mcp list

Checking MCP server health...

pingOne: pingone-mcp-server run - ✓ Connected

Use with Cursor

For 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)>>"
      }
    }
  }
}

{
  "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)>>"
      }
    }
  }
}

Building from Source

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)>>",
      },
    },
  }
}

Authentication and Authorization

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.

1. 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
2. Token Storage - Access tokens stored securely in OS keychain where available (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

Tool Configuration

[!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.

Enabling Write Tools

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), add the --disable-read-only flag when starting the server:

pingone-mcp-server run --disable-read-only

Or 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.

Specifying Tools and Tool Collections

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.

Available Flags

• --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 operations)

Filtering Behavior

Priority Rules:

1. Exclusions take priority - If a tool appears in both include and exclude lists, it will be excluded
2. 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)
3. Read-only filter applies to tools - The --disable-read-only flag 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,environments

This 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,environments

This 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 populations

This 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_environments

This 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_application

This 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_application

This 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

Tool collections group related tools together for easier management. Each collection corresponds to a PingOne resource type.

Available Tools

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

Applications

Create, update, view applications within an environment.

Directory Operations

Read or manage directory operations within an environment.

Environments

Manage PingOne environments and their services.

Populations

Manage user populations within environments.

Security

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

Troubleshooting

Having issues with the MCP server? Check the comprehensive 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 for details.

Contributing

Feedback and 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.

Pull Request Guidelines

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 for more information.