Pega DX MCP Server

Enabling conversational interaction with Pega Infinity™ applications

This package transforms Pega Infinity™ interactions into intuitive, conversational experiences through the Model Context Protocol. By bridging Pega DX API with natural language interfaces, it enables GenAI Agents, IDEs, and other MCP-enabled tools to interact with Pega Infinity™ applications using simple, human-readable commands.

🧪 Experimental

The Pega DX MCP Server is an experimental project exploring the intersection of Model Context Protocol and Pega Infinity™ capabilities. This is not an official Pegasystems product and is not generally available. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Do not use this MCP server for production functionality. This experiment demonstrates the potential of natural language interfaces for Pega Infinity™ interactions. We welcome feedback and contributions to help shape the future of GenAI-powered business automation.

📡 API Support

• Constellation DX API (V2): ✅ Fully supported with 60+ tools
• Traditional DX API (V1): 🚧 Work in progress - Basic support for cases and case types

🌟 Key Features

• 🤖 Natural Language Interface - Demonstrates conversational case creation: "Create a travel claim for John"
• 🔌 Plug-and-Play Integration - Experimental compatibility with GenAI Agents, IDEs, and MCP-enabled tools
• 🧪 Innovation Prototype - Exploring enterprise-grade patterns with comprehensive error handling approaches
• 📡 API Integration Exploration - Investigating access to cases, assignments, attachments, and data operations with 67 comprehensive tools
• ⚡ Performance Research - Experimenting with intelligent caching and optimization strategies
• 🛡️ Security Framework - Implementing OAuth 2.1 with PKCE and role-based access control patterns

🚀 Quick Start

Prerequisites

• Node.js (22+) and npm
• Access to Pega Infinity™ (23+) with DX API enabled
• OAuth 2.1 client credentials

Installation

# Install from npm 
npm install -g @marco-looy/pega-dx-mcp

Integration with MCP Clients

Compatible with Claude Desktop, Claude Code, Cline, and many other MCP-enabled applications.

Claude Code (Recommended)

Use the claude mcp add-json command to add the server:

claude mcp add-json pega-dx-mcp '{"command":"npx","args": ["-y", "@marco-looy/pega-dx-mcp"],"env":{"PEGA_BASE_URL":"https://your-pega-instance.com","PEGA_CLIENT_ID":"your-client-id","PEGA_CLIENT_SECRET":"your-client-secret","PEGA_API_VERSION":"v2","PEGA_ASSIGNMENT_TOOLS":"true","PEGA_ATTACHMENT_TOOLS":"true","PEGA_CASE_TOOLS":"true","PEGA_CASETYPE_TOOLS":"true","PEGA_DATAVIEW_TOOLS":"true","PEGA_DOCUMENT_TOOLS":"true","PEGA_FOLLOWER_TOOLS":"true","PEGA_PARTICIPANT_TOOLS":"true","PEGA_RELATED_CASE_TOOLS":"true","PEGA_SERVICE_TOOLS":"true","PEGA_TAG_TOOLS":"true","LOG_LEVEL":"info"}}'

Or for development/local testing, navigate to this project directory and run:

claude mcp add-json pega-dx-mcp '{"command":"node","args": ["src/index.js"],"env":{"PEGA_BASE_URL":"https://your-pega-instance.com","PEGA_CLIENT_ID":"your-client-id","PEGA_CLIENT_SECRET":"your-client-secret","PEGA_API_VERSION":"v2","PEGA_ASSIGNMENT_TOOLS":"true","PEGA_ATTACHMENT_TOOLS":"true","PEGA_CASE_TOOLS":"true","PEGA_CASETYPE_TOOLS":"true","PEGA_DATAVIEW_TOOLS":"true","PEGA_DOCUMENT_TOOLS":"true","PEGA_FOLLOWER_TOOLS":"true","PEGA_PARTICIPANT_TOOLS":"true","PEGA_RELATED_CASE_TOOLS":"true","PEGA_SERVICE_TOOLS":"true","PEGA_TAG_TOOLS":"true","LOG_LEVEL":"info"}}'

Other MCP Clients

Add to your MCP client's configuration file:

{
  "mcpServers": {
    "pega-dx-mcp": {
      "command": "npx",
      "args": ["-y", "@marco-looy/pega-dx-mcp"],
      "env": {
        "PEGA_BASE_URL": "https://your-pega-instance.com",
        "PEGA_CLIENT_ID": "your-client-id",
        "PEGA_CLIENT_SECRET": "your-client-secret",
        "PEGA_API_VERSION":"v2"
      }
    }
  }
}

For local:

{
  "mcpServers": {
    "pega-dx-mcp": {
      "command": "node",
      "args": ["src/index.js"],
      "env": {
        "PEGA_BASE_URL": "https://your-pega-instance.com",
        "PEGA_CLIENT_ID": "your-client-id",
        "PEGA_CLIENT_SECRET": "your-client-secret",
        "PEGA_API_VERSION":"v2"
      }
    }
  }
}

Configuration file locations:

• Claude Desktop: See Claude Desktop documentation how to add an MCP Server
• Claude Code: Use claude mcp add-json command above or see configure MCP Servers
• Cline: See Cline documentation how to edit Cline MCP settings

TIP: Restart your MCP client and confirm the Pega DX MCP tools are available.

🏗️ Architecture

The Pega DX MCP Server bridges GenAI applications with Pega Infinity using the Model Context Protocol:

🛠️ Available Tools

The Pega DX MCP Server provides 67 comprehensive tools organized into 11 functional categories. Each category can be enabled or disabled via environment variables for granular control.

🔧 Tool Configuration

Control which tool categories are loaded using environment variables in your MCP client configuration. All categories are enabled by default - set to "false" to disable:

Example - Only core case management tools enabled:

{
  "mcpServers": {
    "pega-dx-mcp": {
      "command": "npx",
      "args": ["-y", "@marco-looy/pega-dx-mcp"],
      "env": {
        "PEGA_BASE_URL": "https://your-pega-instance.com",
        "PEGA_CLIENT_ID": "your-client-id",
        "PEGA_CLIENT_SECRET": "your-client-secret",
        "PEGA_API_VERSION":"v2",
        "PEGA_SERVICE_TOOLS": "true",
        "PEGA_CASETYPE_TOOLS": "true",
        "PEGA_CASE_TOOLS": "true",
        "PEGA_ASSIGNMENT_TOOLS": "false",
        "PEGA_ATTACHMENT_TOOLS": "false",
        "PEGA_DATAVIEW_TOOLS": "false",
        "PEGA_DOCUMENT_TOOLS": "false",
        "PEGA_FOLLOWER_TOOLS": "false",
        "PEGA_PARTICIPANT_TOOLS": "false",
        "PEGA_RELATED_CASE_TOOLS": "false",
        "PEGA_TAG_TOOLS": "false"
      }
    }
  }
}

📋 Complete Tool Inventory

Assignment Tools (9)

• get_assignment - Get detailed assignment information
• get_assignment_action - Get assignment action details and UI metadata
• get_next_assignment - Get next work assignment for user
• jump_to_step - Navigate to specific step in assignment flow
• navigate_assignment_previous - Navigate to previous step in assignment
• perform_assignment_action - Execute assignment actions
• recalculate_assignment_fields - Recalculate assignment form fields
• refresh_assignment_action - Refresh assignment action form data
• save_assignment_action - Save assignment form data without executing

Attachment Tools (7)

• add_case_attachments - Attach files/URLs to cases
• delete_attachment - Remove attachments from cases
• get_attachment - Retrieve attachment content
• get_attachment_categories - List available attachment categories
• get_case_attachments - List all case attachments
• update_attachment - Update attachment metadata
• upload_attachment - Upload files as temporary attachments

Case Tools (20)

• add_optional_process - Add stage or case-wide optional processes
• bulk_cases_patch - Perform actions on multiple cases
• change_to_next_stage - Navigate case to next stage
• change_to_stage - Navigate case to specific stage
• create_case - Create new cases with content
• delete_case - Delete cases in create stage
• get_case - Retrieve detailed case information
• get_case_action - Get case action details and metadata
• get_case_ancestors - Get case ancestor hierarchy
• get_case_descendants - Get case descendant hierarchy
• get_case_stages - List case stages and processes
• get_case_view - Get specific case view details
• get_case_view_calculated_fields - Calculate case view fields
• get_cases - Get all cases created by authenticated user (V1 EXCLUSIVE)
• perform_bulk_action - Execute bulk case operations
• perform_case_action - Execute case-wide actions
• recalculate_case_action_fields - Recalculate case action fields
• refresh_case_action - Refresh case action form data
• release_case_lock - Release pessimistic case locks
• update_case - Update case by modifying properties directly (V1 EXCLUSIVE)

Case Type Tools (3)

• get_case_type_action - Get case type action metadata
• get_case_type_bulk_action - Get bulk action metadata for case types
• get_case_types - List available case types

Data View Tools (7)

• delete_data_record - Delete data records from savable data pages
• get_data_objects - List available data objects
• get_data_view_count - Get data view result counts
• get_data_view_metadata - Get data view metadata and parameters
• get_list_data_view - Query list data views with filtering
• update_data_record_full - Fully update data records
• update_data_record_partial - Partially update data records

Document Tools (2)

• get_document - Retrieve document content as base64
• remove_case_document - Remove documents linked to cases

Follower Tools (3)

• add_case_followers - Add users as case followers
• delete_case_follower - Remove case followers
• get_case_followers - List case followers

Participant Tools (7)

• create_case_participant - Add participants to cases
• delete_participant - Remove case participants
• get_case_participants - List all case participants
• get_participant - Get specific participant details
• get_participant_role_details - Get participant role information
• get_participant_roles - List available participant roles
• update_participant - Update participant information

Related Case Tools (3)

• delete_related_case - Remove case relationships
• get_related_cases - List related cases
• relate_cases - Create case relationships

Service Tools (3)

• authenticate_pega - Authenticate with Pega Infinity using OAuth2
• diagnose_pega_config - Diagnose configuration and troubleshoot connection issues
• ping_pega_service - Test connectivity and system availability

Tag Tools (3)

• add_case_tags - Add tags to cases
• delete_case_tag - Remove specific case tags
• get_case_tags - List case tags

💬 Usage Examples

Note: The following examples demonstrate envisioned capabilities and planned user experiences. These scenarios represent the experimental goals of this GenAI Innovation project and may not reflect current implementation status.

Creating a Case

User: "Create a new insurance claim for policy #12345"
AI: I'll create a new insurance claim case. What type of claim is this?
User: "Auto accident claim"
AI: ✅ Created auto accident claim case INS-CLAIM-789
    Case ID: INS-CLAIM-789
    Policy: #12345
    Status: Open
    Next step: Provide accident details

Managing Assignments

User: "What's my next assignment?"
AI: You have 3 pending assignments:
    1. Review claim documentation (INS-CLAIM-789) - Due today
    2. Approve travel request (TRAVEL-456) - Due tomorrow
    3. Customer callback (SERVICE-123) - Due in 2 hours
User: "Let me work on the claim review"
AI: ✅ Opening claim documentation review for INS-CLAIM-789
    [Displays relevant case data and required actions]

⚙️ Configuration

Environment Variables

# Pega Infinity Connection
PEGA_BASE_URL=https://your-pega-instance.com
PEGA_API_VERSION=v2  # Optional: v1 or v2 (defaults to v2)

# OAuth 2.1 Authentication
PEGA_CLIENT_ID=your-oauth-client-id
PEGA_CLIENT_SECRET=your-oauth-client-secret

Important Notes:

• Base URL Format: Do not include /prweb in PEGA_BASE_URL - it will be automatically appended. If present, it will be auto-cleaned with a warning.
• Startup Authentication: The server automatically attempts authentication at startup using environment credentials to provide fail-fast feedback and cache OAuth tokens for faster first API calls.
• Session-Only Mode: If environment credentials are not configured, the server starts in session-only mode where you must provide sessionCredentials with each tool call.

OAuth Setup

1. Register OAuth Client in your Pega Infinity instance
2. Configure Scopes for API access
3. Set Redirect URIs if using authorization code flow
4. Update Environment with client credentials

For detailed setup instructions, see our Configuration Guide.

🤝 Contributing

Join us in this exciting GenAI Innovation experiment! As an experimental project exploring the future of natural language interfaces for enterprise platforms, we welcome community participation in shaping this innovation journey.

Ways to Contribute

• 🔬 Experiment Feedback - Share your experiences and insights from testing the prototype
• 💡 Innovation Ideas - Contribute to the GenAI Innovation roadmap with creative suggestions
• 🐛 Issue Reports - Help identify challenges in this experimental project
• 🔧 Code Contributions - Contribute to the codebase and proof-of-concept features
• 📖 Documentation - Help document learnings and experimental outcomes
• 🧪 Testing & Validation - Participate in testing new experimental capabilities

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/pega-dx-mcp.git
cd pega-dx-mcp

# Install dependencies
npm install

# Create a feature branch
git checkout -b feature/your-feature-name

# Make changes and test
npm test

# Submit pull request

Guidelines

• Follow our Code of Conduct
• Ensure tests pass and add new tests for features
• Update documentation for any API changes
• Use conventional commit messages

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE for details.