ping-iga-mcp-server

MCP server exposing Ping IGA self-service governance operations — access requests, approvals, certifications, and manual tasks — to MCP clients, acting on behalf of the authenticated user.

Stack: JavaScript (ES modules) on Node 20 + Express. No TypeScript, no build step. Zod for runtime validation. MCP 2026-07-28 stateless transport.

Status: Phase 1 complete. Auth (introspection, throttle, rate-limit, RFC 9728 metadata) is wired. The /mcp endpoint and governance tools are built out phase by phase per the implementation plan.

Requirements

• Node 20 LTS (.nvmrc pins 20)

Getting started

nvm use          # Node 20
npm install
cp .env.example .env   # adjust as needed
npm run dev           # starts with --watch on http://localhost:3000
curl http://localhost:3000/healthz   # -> {"status":"ok"}

Scripts

Script	Purpose
npm run dev	Start with node --watch
npm start	Start once
npm test	Run vitest
npm run lint	ESLint
npm run format	Prettier write
npm run inspector	Launch MCP Inspector against the server

401 → metadata → token walkthrough

With the server running (npm run dev) and .env populated, the full bootstrap flow can be traced manually:

Step 1 — hit a protected route without a token; receive a metadata pointer

curl -si http://localhost:3000/_authcheck
# HTTP/1.1 401
# WWW-Authenticate: Bearer resource_metadata="https://<PUBLIC_URL>/.well-known/oauth-protected-resource"

Step 2 — fetch the resource-server metadata document (no token needed)

curl -s http://localhost:3000/.well-known/oauth-protected-resource | jq .
# {
#   "resource": "https://<PUBLIC_URL>",
#   "authorization_servers": ["https://<AIC_BASE_URL>/am/oauth2"],
#   "scopes_supported": ["iga:read", "iga:write", "iga:mutate"],
#   "bearer_methods_supported": ["header"]
# }

Step 3 — obtain a token from the authorization server listed above

Use the authorization_servers[0] URL with your preferred OAuth 2.0 flow (client credentials, authorization code, device flow — whichever your AIC tenant and client registration support). The resulting access token must have at least the iga:read scope.

Step 4 — call the probe route with the token

TOKEN=<access token from step 3>
curl -si http://localhost:3000/_authcheck \
  -H "Authorization: Bearer $TOKEN"
# HTTP/1.1 200
# {"sub":"<user>","scopes":["iga:read",...]}

/_authcheck is a throwaway probe route (D1=a) that will be removed when /mcp lands in Phase 2.

Deployment prerequisites

Beyond the skeleton, running the server against a tenant requires AIC configuration (a confidential client for token introspection, MCP tool-gating scopes, client registration, and verification of the tenant's token model). These are enumerated in the implementation plan and expanded in this README as each phase lands.

WebStorm

Shared run configurations for dev, test, and inspector are committed under .run/. Open the project folder in WebStorm; set the project Node interpreter to your Node 20 install. The .idea/ folder is intentionally not committed — WebStorm generates it on first open.