Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/services/authenticate.js:15-27 (registration)

  Tool definition including name 'authenticate_pega', description, and inputSchema for registration in MCP protocol.

  static getDefinition() {
    return {
      name: 'authenticate_pega',
      description: 'Authenticate with Pega Infinity server using OAuth2 client credentials or direct access token. Stores the authentication token in session for use by other tools. This tool should be used before making API calls when you want to explicitly manage authentication.',
      inputSchema: {
        type: 'object',
        properties: {
          sessionCredentials: getSessionCredentialsSchema()
        },
        required: []
      }
    };
  }

• src/tools/services/authenticate.js:32-64 (handler)

  Main handler function that orchestrates authentication process: initializes session, authenticates via helper, handles success/error, and returns formatted response.

  async execute(params) {
    let sessionInfo = null;
  
    try {
      // Initialize session configuration if provided
      sessionInfo = this.initializeSessionConfig(params);
  
      // Perform authentication
      const result = await this.authenticateAndStore();
  
      if (result.success) {
        return {
          content: [
            {
              type: 'text',
              text: this.formatAuthenticationResponse(result.data, sessionInfo)
            }
          ]
        };
      } else {
        return this.createResponse(false, 'Authenticate Pega', result.error);
      }
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `## Error: Authenticate Pega\n\n**Unexpected Error**: ${error.message}\n\n${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*`
          }
        ]
      };
    }
  }

• src/tools/services/authenticate.js:70-144 (helper)

  Core helper performing the actual OAuth2 authentication, token retrieval/storage, expiry calculation, configuration gathering, and detailed error handling.

  async authenticateAndStore() {
    const startTime = Date.now();
  
    try {
      // Get OAuth2 client from PegaClient
      const oauth2Client = this.pegaClient.client.oauth2Client;
  
      // Attempt to get or fetch access token
      const token = await oauth2Client.getAccessToken();
  
      const duration = Date.now() - startTime;
  
      // Get token info (without exposing actual token)
      const tokenInfo = oauth2Client.getTokenInfo();
  
      // Calculate expiry time
      const expiresInSeconds = tokenInfo.tokenExpiry
        ? Math.round((tokenInfo.tokenExpiry - Date.now()) / 1000)
        : 0;
  
      return {
        success: true,
        data: {
          timestamp: new Date().toISOString(),
          duration: `${duration}ms`,
          sessionId: oauth2Client.cacheKey,
          authMode: oauth2Client.authMode,
          tokenInfo: {
            type: 'Bearer',
            length: token ? token.length : 0,
            prefix: token ? token.substring(0, 10) + '...' : 'None',
            acquired: !!token,
            cached: !!oauth2Client.accessToken,
            expiresIn: expiresInSeconds,
            expiresAt: tokenInfo.tokenExpiry ? new Date(tokenInfo.tokenExpiry).toISOString() : null
          },
          configuration: {
            baseUrl: this.pegaClient.client.config.pega.baseUrl,
            apiVersion: this.pegaClient.getApiVersion(),
            tokenUrl: oauth2Client.authMode === 'oauth'
              ? this.pegaClient.client.config.pega.tokenUrl
              : 'Direct Token',
            configSource: tokenInfo.configSource
          }
        }
      };
    } catch (error) {
      const duration = Date.now() - startTime;
      const oauth2Client = this.pegaClient.client.oauth2Client;
  
      return {
        success: false,
        error: {
          type: 'AUTHENTICATION_ERROR',
          message: `${oauth2Client.authMode.toUpperCase()} authentication failed`,
          details: error.message,
          timestamp: new Date().toISOString(),
          duration: `${duration}ms`,
          authMode: oauth2Client.authMode,
          troubleshooting: oauth2Client.authMode === 'oauth' ? [
            'Verify baseUrl is correct and accessible',
            'Check clientId and clientSecret are valid',
            'Ensure OAuth2 client is configured in Pega Infinity',
            'Verify network connectivity to Pega instance',
            'Check that the OAuth2 client has appropriate permissions'
          ] : [
            'Verify the provided access token is valid',
            'Check if the token has expired',
            'Ensure the token has appropriate permissions',
            'Verify network connectivity to Pega instance'
          ]
        }
      };
    }
  }

• src/tools/services/authenticate.js:152-196 (helper)

  Helper function to format the detailed success response in markdown, including session, config, token info, and next steps.

  formatAuthenticationResponse(data, sessionInfo = null) {
    let response = `## Authenticate Pega\n\n`;
    response += `✅ **Authentication Successful**\n\n`;
    response += `*Completed at: ${data.timestamp}*\n`;
    response += `*Duration: ${data.duration}*\n\n`;
  
    // Session Information
    response += `### Session Information\n`;
    response += `- **Session ID**: ${data.sessionId}\n`;
    response += `- **Authentication Mode**: ${data.authMode.toUpperCase()}\n`;
    response += `- **Configuration Source**: ${data.configuration.configSource}\n`;
    response += '\n';
  
    // Configuration Section
    response += `### Configuration\n`;
    response += `- **Base URL**: ${data.configuration.baseUrl}\n`;
    response += `- **API Version**: ${data.configuration.apiVersion}\n`;
    response += `- **Token URL**: ${data.configuration.tokenUrl}\n`;
    response += '\n';
  
    // Token Information Section
    response += `### Token Information\n`;
    response += `- **Type**: ${data.tokenInfo.type}\n`;
    response += `- **Length**: ${data.tokenInfo.length} characters\n`;
    response += `- **Prefix**: ${data.tokenInfo.prefix}\n`;
    response += `- **Acquired**: ${data.tokenInfo.acquired ? 'Yes' : 'No'}\n`;
    response += `- **Cached**: ${data.tokenInfo.cached ? 'Yes' : 'No'}\n`;
    if (data.tokenInfo.expiresIn > 0) {
      response += `- **Expires In**: ${data.tokenInfo.expiresIn} seconds (${Math.round(data.tokenInfo.expiresIn / 60)} minutes)\n`;
      response += `- **Expires At**: ${data.tokenInfo.expiresAt}\n`;
    }
    response += '\n';
  
    // Usage Instructions
    response += `### Next Steps\n`;
    response += `The authentication token has been stored in the session cache. You can now:\n`;
    response += `- Use other Pega tools without re-authenticating\n`;
    response += `- Test connectivity with the \`ping_pega_service\` tool\n`;
    if (sessionInfo) {
      response += `- Reference this session using sessionId: \`${data.sessionId}\`\n`;
    }
    response += '\n';
  
    return response;
  }