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.

[!WARNING] SECURITY & LEAST PRIVILEGE: This server grants an AI model significant access to your DaVinci environment configuration. All data returned from tools may be sent to the LLM provider.

1. Use ONLY with trusted MCP clients.
2. Follow the Principle of Least Privilege: Ensure the authenticating user is assigned a role with the minimum necessary permissions (e.g., DaVinci Admin Read Only).
3. HUMAN REVIEW REQUIRED: Always review all AI-generated configurations or insights before applying them to a live environment.

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

Tool	Description
list_applications	Returns a list of all DaVinci applications.
describe_application	Returns details of a single DaVinci application by ID.
list_application_flow_policies	Returns all flow policies for a DaVinci application.
describe_application_flow_policy	Returns details of a single flow policy for a DaVinci application.

Flow Tools

Tool	Description
list_flows	Returns a list of all DaVinci flows. Supports attributes to project the response to specific top-level fields. Flow type is derived from the trigger field: no trigger = standard flow; trigger.type AUTHENTICATION = PingOne flow; trigger.type AUTHENTICATION + trigger.subtype CIBA = CIBA flow; trigger.type SCHEDULE = scheduled flow; trigger.type BATCH_PROCESSING_SUBFLOW = batch processing subflow. readOnly: true means the flow is read-only.
describe_flow	Returns the complete definition of a DaVinci flow including the full node graph, edges, and settings. Use when auditing or understanding a flow's internal logic. Supports attributes to project the response to specific top-level fields and expand to include related fields inline (e.g. "dvlinterDetails").
list_flow_versions	Returns all versions of a specific DaVinci flow.
describe_flow_version	Returns the complete definition of a specific DaVinci flow version, including the full node graph, edges, settings, and trigger configuration. Supports expand to include related fields inline (e.g. skcomponents).

Connector Tools

Tool	Description
list_connectors	Returns a list of all available DaVinci connector types from the catalog.
describe_connector	Returns the full details of a single DaVinci connector type by ID, including metadata, capabilities, configurable properties, and required credentials.
list_connector_instances	Returns a list of all deployed DaVinci connector instances.
describe_connector_instance	Returns details of a single deployed DaVinci connector instance by ID.

Variable Tools

Tool	Description
list_variables	Returns a list of all DaVinci variables. Supports limit (1–50), cursor for pagination, and a SCIM filter to narrow results.
describe_variable	Returns details of a single DaVinci variable by ID.

Form Tools

Tool	Description
list_forms	Returns a list of all DaVinci forms. Use for discovery and finding form IDs. Use describe_form for field-level details. Supports a SCIM filter on category (eq).
describe_form	Returns full configuration of a single DaVinci form including fields and layout.

Collection: davinci_flow_troubleshooting

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

Flow Troubleshooting Tools

Tool	Description
validate_flow	Validates a DaVinci flow configuration using the DVLinter validation engine. Use this tool to check deployment readiness, identify configuration errors and warnings (best-practice violations), and troubleshoot flow issues. Analyzes nodes (connectors and capabilities), connections (connector instances), node properties, and overall structure. Returns validation results including error counts or warning counts, and specific issue descriptions. Error locations: (1) linterError property within each node in graphData.elements.nodes for node specific issues (2) allLinterErrors property in graphData for all flow-level errors and warnings. Zero errors indicates deployment-ready status. This is a read-only operation that does not modify the flow.
list_flow_executions	Returns a list of all executions for a specific DaVinci flow. Use this tool to find execution IDs for troubleshooting, debugging, or monitoring flow executions. Supports limit (max 500) and cursor for pagination and SCIM filter on timestamp (ge, le) with ISO 8601 dates, transactionId (eq) for specific transaction details.
summarize_flow_execution	Returns detailed information about a specific DaVinci flow execution with status (success/failure), timestamps, input/output data, errors with stack traces, and user context. Use this tool to debug failures, summarize flow execution results, analyze execution behavior, verify data transformations, or investigate user-specific issues. Supports limit (max 500) and cursor for pagination and SCIM filter on timestamp (ge, le) with ISO 8601 dates.

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

Variable	Description	Example
DAVINCI_MCP_ENVIRONMENT_ID	The ID of your PingOne environment.	a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6
AUTHORIZATION_CODE_CLIENT_ID	The Client ID of your PingOne Worker Application.	your-client-id
ROOT_DOMAIN	The regional PingOne domain.	pingone.com (NA), pingone.eu (EU), pingone.asia (APAC)
CUSTOM_DOMAIN	(Optional) Your custom PingOne domain.	auth.example.com

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.

<details> <summary>Claude Desktop</summary>

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

</details>

<details> <summary>Claude Code (CLI)</summary>

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

</details>

<details> <summary>VS Code (Cline)</summary>

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

</details>

<details> <summary>Cursor</summary>

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 </details>

<details> <summary>Gemini CLI</summary>

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

</details>

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

<details> <summary><b>1. Basic Server Startup</b></summary> The standard configuration to run the server with all default tools enabled.

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

</details>

<details> <summary><b>2. Filter by Tool Collection</b></summary> Limit the tools exposed to Claude to only those in the davinci_admin collection.

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

</details>

<details> <summary><b>2a. Include Flow Troubleshooting Tools Only</b></summary> Expose only the flow troubleshooting and debugging tools.

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

</details>

<details> <summary><b>3. Filter by Specific Tools</b></summary> Expose only a surgical set of tools (e.g., only flows) to the AI assistant.

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

</details>

<details> <summary><b>4. Exclude Specific Tools</b></summary> Enable all tools except for those related to variables.

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

</details>

<details> <summary><b>5. Enable Verbose Logging</b></summary> Enable detailed logging to help debug connection or tool execution issues.

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

</details>

Maintenance & Utility Commands

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

<details> <summary><b>1. Logout & Clear Credentials</b></summary> Force the server to clear stored tokens from the system keychain. This is useful if you need to switch users or re-authenticate.

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

</details>

<details> <summary><b>2. Display Help</b></summary> View all available commands, options, and required environment variables directly in your terminal.

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

</details>

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.