pi-pega-mcp-bridge

Run Pega Infinity authoring inside the pi coding agent. This extension spawns Pega's own MCP server (infinity-rules-mcp.jar from pegasystems/infinity-ai-plugins) and registers its tools in pi as native tools. In a read-only session you get 22 tools: search and read rules, list case types, browse Pega's authoring skills, run data pages and PegaUnit tests. Enable write mode and you also get rule and case authoring through Pega's ChangeRequest workflow.

No MCP client plugin is installed into pi. The bridge spawns Pega's own server as a subprocess and speaks JSON-RPC over stdio, so the tools appear to the model exactly like built-in pi tools.

Not affiliated with or endorsed by Pegasystems Inc. This package ships no Pega code or binaries; it launches the server from Pega's own repository, which you clone separately.

How it works

pi session
  └── extensions/pega-mcp.ts          (this bridge)
        └── spawns: java -jar infinity-rules-mcp.jar --spring.profiles.active=stdio
              └── tools/list  →  registered as native pi tools (once per pi process)
              └── tools/call  →  forwarded per tool call
              └── OAuth: browser-based login, loopback callback on localhost:8888
              └── talks to your Pega Infinity environment REST APIs

Related MCP server: lnwjud

Why not pi-mcp-adapter?

pi-mcp-adapter is a fine generic MCP client for pi, and pointing it at Pega's jar works. This package exists because generic gets you none of the Pega-specific decisions: all 29 tools registered with write access on day one, no integrity check on the jar, no setup flow for the OAuth client and redirect URI, and no help with the config mistakes Pega's docs invite (a /prweb suffix in the URL, a missing PEGA_SKILLS_PATH). If you want those safety defaults handled for you, use this bridge. If you want full control, the adapter is a reasonable path.

Prerequisites

Install Java

macOS:

brew install openjdk@17

Linux (Debian/Ubuntu):

sudo apt install openjdk-17-jre

Linux (RHEL/Fedora): sudo dnf install java-17-openjdk

Windows:

winget install EclipseAdoptium.Temurin.17.JRE

Verify with java -version.

Clone the Pega repo

The bridge looks for the jar at ~/.pi/agent/pega/infinity-ai-plugins/plugins/pega/infinity-ai-plugins/claude/resources/infinity-rules-mcp.jar (Windows: %USERPROFILE%\.pi\agent\pega\..., resolved automatically). Use a different location by setting PEGA_PLUGIN_DIR to the plugins/pega/infinity-ai-plugins/claude directory.

mkdir -p ~/.pi/agent/pega
git clone https://github.com/pegasystems/infinity-ai-plugins.git ~/.pi/agent/pega/infinity-ai-plugins

You do not need to install the Pega plugin into Claude Code, Codex, or Copilot CLI. The clone is all this bridge uses.

Pega-side setup (one time per environment)

1. In Pega, create an OAuth 2.0 client registration (Records → Integration → Services):

   • Client credentials type: Public (no secret)

   • Grant type: Authorization code

   • Redirect URI: http://localhost:8888/callback (exact scheme, port, and path)

2. Note the generated client ID.

3. The bridge connects as your Pega user. Everything it does happens with your permissions, so scope the client registration's access group accordingly.

Install

pi install git:github.com/WeekendNoobs/pi-pega-mcp-bridge

Or, to try it without installing:

pi -e git:github.com/WeekendNoobs/pi-pega-mcp-bridge

Configure the connection

Create ~/.infinity-rules-mcp/config.json (%USERPROFILE%\.infinity-rules-mcp\config.json on Windows). This is the same file Pega's official plugins use:

{
  "pega_base_url": "https://your-environment.example.com",
  "pega_oauth_client_id": "<your-client-id>",
  "pega_infinity_version": "26-1"
}

• pega_base_url: environment root only. No /prweb, no path segments.

• pega_infinity_version: one of 24-2, 25-1, 26-1. Defaults to 26-1.

Restrict the file on macOS/Linux: chmod 600 ~/.infinity-rules-mcp/config.json. The bridge warns at session start if the mode differs. The file is plaintext and gates access to your Pega environment; never commit it.

Start a new pi session. The first Pega tool call opens a browser for OAuth login. The session token is persisted, so you log in once, not per call.

Read-only by default

The bridge registers 22 read tools by default. Seven data-mutating tools are withheld unless you explicitly enable them:

create-case, perform-action, trigger-optional-process, initiate-authoring-change, copy-rule, create-rule, update-rule

To enable write access for a session:

PEGA_MCP_WRITE_TOOLS=1 pi

Writes go through Pega's ChangeRequest workflow (branch rulesets), which is Pega's own recommended authoring pattern. Ask the agent for get-skill("recipes/change-request-workflow") before your first write session.

Commands

• /pega-status: server state, mode, registered tool count, config summary, last error

• /pega-restart: restart the jar, picks up config.json changes and Pega repo updates

Configuration reference

~/.infinity-rules-mcp/config.json (Pega's format)

Bridge environment variables

Security model

• Read-only default. Write tools are opt-in per session (see above).

• Jar integrity pin. The bridge embeds the SHA-256 of the tested infinity-rules-mcp.jar. A mismatch (for example after git pull in the Pega repo) refuses to start and prints the actual hash. Update the pin deliberately via PEGA_MCP_EXPECTED_JAR_SHA256 or by updating this package; never let a repo pull silently swap the executable.

• Loopback OAuth. Pega's server implements the authorization code flow over http://localhost:8888/callback with no PKCE. On a single-user machine this is standard practice; on shared hosts any local process could race the callback port. If port 8888 is occupied, set PEGA_OAUTH_REDIRECT_PORT in the environment and register the matching redirect URI in Pega. Both sides must change together.

• Operator scope. Tool calls execute as your Pega user through the client registration you created. Treat agent-initiated writes like any other change made by your account.

• Server logs. The jar writes logs into the clone under plugins/pega/infinity-ai-plugins/claude/resources/logs/. They can contain API traffic and case data. Do not commit or share that directory.

• Pega license boundary. This repository contains no Pegasystems code, binaries, or content. The jar and its skills payload are cloned from Pega's repository and remain governed by the "Pega Infinity AI Plugins License" shipped there, which permits use solely in connection with Pegasystems software. See LICENSE in this repo for the third-party notice.

Troubleshooting

Platform note: developed and tested on macOS (Apple Silicon). Linux and Windows use standard Node.js APIs and are expected to work. If something breaks on your platform, include your OS, Java vendor and version, and the full /pega-status output in the issue.

Updating

• This bridge: pi update --extensions

• Pega's server: git pull in the clone at ~/.pi/agent/pega/infinity-ai-plugins, then /pega-restart. If the jar hash changed, the bridge will refuse to start until you update the pin (see Security model). This is intentional.

Verify the connection outside pi

node scripts/verify.mjs

Spawns the jar directly, performs the MCP handshake, and calls list-available-applications. Useful to separate bridge problems from Pega environment problems.

License

MIT for this package's code. See LICENSE for details and the third-party notice regarding Pega components.