pega-mcp-server

Generic TypeScript MCP server for Pega case operations with definition-driven tool registration.

Purpose

This project provides an MCP tool layer for reading and mutating cases in a flexible way. Tool wiring is metadata-based, so adding tools does not require editing server registration logic.

Supported MCP Tools

• pega.get_cases

  • Input: optional limit

  • Returns: { ok: true, data: { cases: [...] } }

• pega.get_case

  • Input: caseId, optional viewType, pageName, originChannel

  • Returns: { ok: true, data: { case: ... } }

• pega.get_case_actions

  • Input: caseId, optional originChannel

  • Returns: { ok: true, data: { actions: ... } }

• pega.get_case_views

  • Input: caseId, viewId, optional originChannel

  • Returns: { ok: true, data: { view: ... } }

• pega.attach_document_to_case

  • Input: caseId, fileName, mimeType, fileContentBase64

  • Returns: { ok: true, data: ... }

• pega.submit_case_action

  • Input: caseId, action, optional content

  • Returns: { ok: true, data: ... }

All tools return a standard failure format:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT | NOT_FOUND_OR_FORBIDDEN | INTERNAL_ERROR",
    "message": "Human-readable explanation",
    "suggestion": "Optional recovery guidance"
  }
}

Environment Variables

Required:

• PEGA_BASE_URL (for example https://your-pega-instance.example.com/prweb)

• PEGA_CLIENT_ID

• PEGA_CLIENT_SECRET

• PEGA_TOKEN_URL (for example https://your-pega-instance.example.com/prweb/PRRestService/oauth2/v1/token)

Optional:

• PEGA_CASES_API_BASE_PATH (default: /api/v1)

  • Common v2 path when base URL includes /prweb: /api/application/v2

  • Some deployments use app context: /PRAuth/app/work-manager/api/application/v2

• PEGA_CASES_LIST_DATA_VIEW (default: D_pyMyWorkList)

  • Used as a fallback for pega.get_cases when GET /cases is not supported (HTTP 405)

  • Endpoint shape: POST <PEGA_CASES_API_BASE_PATH>/data_views/<dataViewId>

• PEGA_ENABLED_TOOLS comma-separated tool names to allowlist

  • Example: pega.get_case,pega.get_case_actions

• PEGA_DISABLED_TOOLS comma-separated tool names to blocklist

  • Example: pega.submit_case_action,pega.attach_document_to_case

Run Locally

npm install
cp .env.example .env
npm run dev

Build

npm run build
npm start

Test

npm test

Example Outputs

pega.get_cases

{
  "ok": true,
  "data": {
    "cases": [
      {
        "ID": "C-501",
        "caseType": "Insurance Claim",
        "status": "Pending Documents"
      }
    ]
  }
}

pega.get_case

{
  "ok": true,
  "data": {
    "case": {
      "ID": "C-501",
      "caseType": "Insurance Claim",
      "status": "Pending Documents",
      "uiResources": {
        "root": {
          "type": "page"
        }
      }
    }
  }
}

Detailed request/response contracts:

• docs/tool-contracts.md