DaVinci MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with seamless access to PingOne's DaVinci identity orchestration platform resources. This server enables AI models to interact with DaVinci flows, applications, connectors, variables, and forms through a standardized interface.

Overview

DaVinci is PingOne's no-code identity orchestration platform that allows organizations to build sophisticated identity and access management workflows. This MCP server acts as a bridge between MCP-compatible AI assistants and the DaVinci API, enabling:

• Flow Management: List and inspect identity orchestration flows and their versions.

• Flow Validation: Check flow configuration errors and deployment readiness.

• Flow Execution Monitoring: Monitor flow executions, review execution history, and troubleshoot failures.

• Application Configuration: Access application settings and flow policies.

• Connector Management: View available connectors and their configurations.

• Variable Management: Manage flow variables and their values.

• Form Management: Access form definitions and configurations.

• Connector Instances: Manage connector instance configurations.

Features

Available Tools

The server provides the following MCP tools organized into two collections:

Collection: davinci_admin

Core administrative tools for managing DaVinci resources (applications, flows, connectors, variables, forms).

Application Tools

Flow Tools

Connector Tools

Variable Tools

Form Tools

Collection: davinci_flow_troubleshooting

Specialized tools for flow validation, execution monitoring, and debugging.

Flow Troubleshooting Tools

Authentication

The server uses OAuth 2.0 Authorization Code flow with PKCE for secure authentication:

• Automatic Token Management: Secure token storage using the system keychain (via keytar).

• Interactive Login: Interactive browser-based authentication flow.

• Regional Support: Support for different PingOne regional domains.

Prerequisites

• Node.js: Version 22.0.0 or higher. (Download & Install)

• PingOne Subscription: A licensed or trial PingOne cloud subscription.

  • If you don't have one, you can sign up for a free trial.

• DaVinci Enabled: Ensure the DaVinci service is added to your environment.

  • In the PingOne Admin Console, navigate to Environments > Your Environment > Services and ensure DaVinci is listed and active.

• Worker Application: A PingOne Worker Application in the same environment (see Setup for details).

• User Permissions: The authenticating user must be created in the environment if not present, and the user must have an appropriate role, such as DaVinci Admin Read Only.

Setup

1. PingOne Worker Application Setup

The MCP server requires a Worker Application to authenticate with the PingOne API.

1. Access PingOne Admin: Log in to your PingOne Admin Console.

2. Select Environment: Choose the environment where DaVinci is enabled.

3. Navigate to Applications: Click Applications > Applications in the left navigation menu.

4. Create Application:

   • Click + Add Application and select Worker.

   • Name: e.g., DaVinci MCP Server.

   • Description: Optional.

   • Click Save.

   • Enable the Worker application by toggling the button on top right.

5. Configure Grant Types:

   • Select the Configuration tab of your new application.

   • Click the Edit (pencil) icon.

   • Under Grant Types, ensure Authorization Code is selected.

   • Under Response Type ensure Code is selected.

   • PKCE Enforcement: Set to S256_REQUIRED.

   • Redirect URIs: Add http://127.0.0.1:7474/callback.

   • Token Endpoint Authentication Method: Set to None (Public Client).

   • Click Save.

6. Capture Credentials:

   • Copy the Client ID from the Configuration tab. You will need this for the AUTHORIZATION_CODE_CLIENT_ID variable.

   • Note your Environment ID (found in the URL or the environment settings).

2. User Setup & Role Assignment

The authenticating user must have the necessary permissions to access DaVinci resources.

1. Navigate to Users: In the PingOne Admin Console, click Directory > Users.

2. Create/Select User: Either create a new user (+ Add User) or select an existing one that you will use to log in via the MCP server.

3. Assign Role:

   • On the user's profile, navigate to the Roles tab.

   • Click Grant Roles.

   • Search for and select the DaVinci Admin Read Only role.

   • Click Save.

3. Configure Environment Variables

The server requires the following environment variables. These should be configured in your MCP client's settings (see Usage below).

Usage

Quick Install

VS Code

Cursor

MCP Client Configuration

Replace your-environment-id and your-client-id with your actual PingOne environment ID and OAuth Client ID in the examples below.

Add the following to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": ["-y", "@ping-identity/davinci-mcp-server", "start"],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

Run the following command in your terminal:

claude mcp add --transport stdio davinci \
--env DAVINCI_MCP_ENVIRONMENT_ID="your-environment-id" \
--env AUTHORIZATION_CODE_CLIENT_ID="your-client-id" \
--env ROOT_DOMAIN="pingone.com" \
-- npx -y @ping-identity/davinci-mcp-server start

1. Open the Cline sidebar in VS Code.

2. Click the Settings (gear) icon.

3. Scroll to MCP Servers and click Add MCP Server.

4. Use the following configuration:

{
  "davinci": {
    "command": "npx",
    "args": ["-y", "@ping-identity/davinci-mcp-server", "start"],
    "env": {
      "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
      "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
      "ROOT_DOMAIN": "pingone.com"
    }
  }
}

1. Open Cursor Settings -> Features -> MCP.

2. Click + Add New MCP Server.

3. Name: davinci

4. Type: command

5. Command:

npx -y @ping-identity/davinci-mcp-server start

6. Add environment variables:

   • DAVINCI_MCP_ENVIRONMENT_ID: your-environment-id

   • AUTHORIZATION_CODE_CLIENT_ID: your-client-id

   • ROOT_DOMAIN: pingone.com

Add the following to your ~/.gemini/settings.json:

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": ["-y", "@ping-identity/davinci-mcp-server", "start"],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

CLI Commands & Flags

The server requires a command to execute and supports several flags to customize its behavior. These should be added to the args array in your MCP client configuration:

Commands

• start: Initiates the MCP server (required for normal operation).

Options

• --include-collections <list>: Comma-separated list of collection names to include (e.g., davinci_admin, davinci_flow_troubleshooting).

• --exclude-collections <list>: Comma-separated list of collection names to exclude.

• --include-tools <list>: Comma-separated list of tool names to include.

• --exclude-tools <list>: Comma-separated list of tool names to exclude.

• --verbose: Enable verbose logging to stderr.

• --logout: Trigger a logout flow on startup by clearing stored tokens.

• --help: Show the help message.

MCP Configuration Examples

These examples show how to configure claude_desktop_config.json for different scenarios. Change accordingly for other providers

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": ["-y", "@ping-identity/davinci-mcp-server", "start"],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": [
        "-y",
        "@ping-identity/davinci-mcp-server",
        "start",
        "--include-collections",
        "davinci_admin"
      ],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": [
        "-y",
        "@ping-identity/davinci-mcp-server",
        "start",
        "--include-collections",
        "davinci_flow_troubleshooting"
      ],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": [
        "-y",
        "@ping-identity/davinci-mcp-server",
        "start",
        "--include-tools",
        "list_flows,describe_flow"
      ],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": [
        "-y",
        "@ping-identity/davinci-mcp-server",
        "start",
        "--exclude-tools",
        "describe_variable,list_variables"
      ],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": ["-y", "@ping-identity/davinci-mcp-server", "start", "--verbose"],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

Maintenance & Utility Commands

These commands are intended to be run manually in your terminal for maintenance or discovery.

npx -y @ping-identity/davinci-mcp-server start --logout

npx -y @ping-identity/davinci-mcp-server --help

Example (Claude Desktop Configuration):

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": [
        "-y",
        "@ping-identity/davinci-mcp-server",
        "start",
        "--include-tools",
        "list_flows,describe_flow",
        "--verbose"
      ],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

Development

1. Installation

git clone https://github.com/pingidentity/davinci-mcp-server.git
cd davinci-mcp-server
npm ci

2. Available Scripts

See the Development Workflow table in CONTRIBUTING.md for the full list of npm scripts.

Troubleshooting

• Port Conflict: The authentication callback server uses port 7474. Ensure this port is available.

• Keychain Access: On Linux, ensure libsecret is installed for keytar to function. On macOS/Windows, it uses the native keychain.

• Authentication Timeout: The browser login must be completed within 5 minutes.

• Invalid Tokens: Use the --logout flag to clear corrupted or invalid tokens from the keychain.

Contributing

See CONTRIBUTING.md for guidelines on setting up the project, code style, adding new tools, writing tests, and submitting pull requests.

License

This project is licensed under the Apache-2.0 License.