portkey-admin-mcp 0.6.2 → 0.7.0

package/docs/PRISMA_AIRS_INTEROPERABILITY.md

@@ -0,0 +1,66 @@
+# Prisma AIRS interoperability
+
+Last verified: 2026-08-09
+
+## Short answer
+
+Portkey is now the core AI Gateway technology in Prisma AIRS, but Prisma AIRS AI Gateway is **not currently a drop-in API target** for this MCP server. Keep using this server for the documented Portkey control-plane API. Use Prisma AIRS alongside it through Strata Cloud Manager and, where useful, Palo Alto Networks' security-focused MCP server.
+
+Changing `PORTKEY_BASE_URL` to a Prisma AIRS or Strata Cloud Manager URL will not work: the public products currently expose different management surfaces, credentials, and resource models.
+
+## Current boundary
+
+| Surface | Management interface | Authentication | What this project supports |
+|---|---|---|---|
+| Portkey Admin API | `https://api.portkey.ai/v1` or a compatible self-hosted control plane | `x-portkey-api-key` | Full support through the 19 existing tool domains |
+| Portkey public model catalog | `https://api.portkey.ai/model-configs/...` | None | `get_model_pricing` |
+| Prisma AIRS AI Gateway | AI Security in Strata Cloud Manager | Prisma AIRS / SCM tenant credentials | No direct admin adapter yet |
+| Prisma AIRS security MCP server | Regional Palo Alto Networks `/mcp` endpoint | `x-pan-token`, OAuth, and optional `x-pan-profile` | Works as a separate MCP server; it scans and secures AI interactions rather than managing Portkey resources |
+
+Palo Alto Networks says the Portkey acquisition makes Portkey the core AI Gateway for Prisma AIRS. Its current AI Gateway instructions direct administrators to Strata Cloud Manager, while the documented Prisma AIRS MCP endpoint is for centralized AI-agent security. No public Prisma AIRS admin contract equivalent to Portkey's users, workspaces, prompts, configs, integrations, or keys is documented today. That last sentence is an inference from the currently published product and API documentation, not a promise that such an API will never exist.
+
+## Recommended coexistence
+
+Run the two MCP servers side by side when you need both administration and runtime security:
+
+```json
+{
+  "mcpServers": {
+    "portkey-admin": {
+      "command": "npx",
+      "args": ["-y", "portkey-admin-mcp"],
+      "env": {
+        "PORTKEY_API_KEY": "your-portkey-key"
+      }
+    },
+    "prisma-airs-security": {
+      "type": "http",
+      "url": "https://service.api.aisecurity.paloaltonetworks.com/mcp",
+      "headers": {
+        "x-pan-token": "your-prisma-airs-key",
+        "x-pan-profile": "your-security-profile"
+      }
+    }
+  }
+}
+```
+
+Use `portkey-admin` for control-plane changes. Use `prisma-airs-security` for the security tools provided by Palo Alto Networks. Choose the documented regional Prisma AIRS endpoint for your tenant, and keep both credentials out of source control.
+
+## When a direct adapter becomes possible
+
+A native Prisma AIRS mode should be added only after Palo Alto Networks publishes a stable management API for AI Gateway. The adapter will need its own:
+
+- base URL and authentication strategy;
+- mapping for tenants, workspaces, guardrails, integrations, and logs;
+- capability detection rather than assuming Portkey endpoint parity;
+- contract fixtures and integration tests against the published API.
+
+That should be a distinct adapter or tool domain, not a silent reinterpretation of `PORTKEY_BASE_URL`, so existing Portkey and self-hosted deployments keep working.
+
+## Official references
+
+- [Palo Alto Networks completes the Portkey acquisition](https://investors.paloaltonetworks.com/news-releases/news-release-details/palo-alto-networks-completes-acquisition-portkey-secure-ai)
+- [Configure Prisma AIRS AI Gateway](https://docs.paloaltonetworks.com/ai-runtime-security/administration/configure-ai-gateway)
+- [Configure the Prisma AIRS security MCP server](https://docs.paloaltonetworks.com/ai-runtime-security/activation-and-onboarding/prisma-airs-mcp-server-for-centralized-ai-agent-security/configure-mcp-server-security-using-prisma-airs)
+- [Portkey OpenAPI](https://github.com/Portkey-AI/openapi)

package/docs/VERCEL_DEPLOYMENT.md

@@ -0,0 +1,192 @@
+# Vercel Deployment Guide (Public Repo Safe)
+
+> **Status (June 2026)**: This deployment path is a **proof of concept kept for reference**. There is no hosted version of this server and hosting is not currently a goal — the supported transport is stdio via `npx`. The steps below remain valid if you want to self-deploy.
+
+This guide describes how to self-deploy this MCP server on Vercel.
+
+## Recommended Architecture
+
+- Runtime: Vercel Node.js Function (`api/index.ts`)
+- Transport: Streamable HTTP (`/mcp`)
+- Session mode: `stateless`
+- Event store: `redis`
+- Auth: `clerk` (preferred for teams) or `bearer` (internal-only)
+
+Why: serverless instances scale and restart, so each POST and replay GET is handled independently. Redis maps the client's `Last-Event-ID` cursor back to the interrupted SSE stream across instances without introducing MCP session affinity.
+
+## 1. Prerequisites
+
+- Portkey Admin API key with required scopes
+- Redis instance URL (for example Upstash Redis or another managed Redis service)
+- Vercel project connected to this repository
+- Optional but recommended: Clerk app for JWT auth
+
+## 2. Verify Repo Files
+
+These files should already exist:
+
+- `api/index.ts`
+- `vercel.json`
+
+`vercel.json` rewrites these routes to the function:
+
+- `/`
+- `/mcp`
+- `/health`
+- `/ready`
+- `/auth/info`
+
+## 3. Configure Vercel Environment Variables
+
+Set these in Vercel Project Settings -> Environment Variables.
+
+Required:
+
+- `PORTKEY_API_KEY`
+- `MCP_SESSION_MODE=stateless`
+- `MCP_EVENT_STORE=redis`
+- `MCP_REDIS_URL=rediss://<ACL-user>:<password>@...`
+- `MCP_EVENT_ENCRYPTION_KEY=<base64-encoded-32-byte-key>`
+- `ALLOWED_ORIGINS=https://your-app-domain`
+- `MCP_TRUST_PROXY=true`
+- `RATE_LIMIT_STORE=redis`
+
+Recommended:
+
+- `MCP_READY_CHECK_MODE=portkey`
+- `RATE_LIMIT_ENABLED=true`
+- `RATE_LIMIT_REDIS_URL=rediss://...` (optional; falls back to `MCP_REDIS_URL`)
+
+The shared limiter applies an IP bucket before authentication and a separate
+principal-plus-IP bucket after authentication.
+
+Generate the replay encryption key locally with `openssl rand -base64 32`. Store
+it only as a Vercel secret. Rotating it makes unexpired replay events unreadable;
+the default replay TTL is five minutes.
+
+Auth option A (recommended for teams): Clerk JWT
+
+- `MCP_AUTH_MODE=clerk`
+- `CLERK_ISSUER=https://<your-clerk-domain>`
+- `CLERK_AUDIENCE=<your-audience>` (required)
+- `CLERK_JWKS_URL=...` (optional; auto-derived from issuer if omitted)
+- At least one authorization constraint: `CLERK_ALLOWED_SUBJECTS`,
+  `CLERK_ALLOWED_ORGANIZATION_IDS`, `CLERK_ALLOWED_ROLES`, or
+  `CLERK_REQUIRED_PERMISSIONS`. Every configured constraint must match.
+
+Auth option B (internal shared token):
+
+- `MCP_AUTH_MODE=bearer`
+- `MCP_AUTH_TOKEN=<long-random-secret>`
+
+Do not set:
+
+- `MCP_TLS_KEY_PATH`
+- `MCP_TLS_CERT_PATH`
+- `MCP_TLS_CA_PATH`
+
+Vercel terminates HTTPS at the edge.
+
+## 4. Deploy
+
+Use Vercel dashboard or CLI:
+
+```bash
+vercel
+vercel --prod
+```
+
+After deploy, your endpoint is:
+
+- `https://<your-project>.vercel.app/mcp`
+
+## 5. Post-Deploy Checks
+
+Unauthenticated endpoints:
+
+```bash
+curl -sS https://<your-project>.vercel.app/health
+curl -sS https://<your-project>.vercel.app/ready
+curl -sS https://<your-project>.vercel.app/auth/info
+```
+
+Set `MCP_PUBLIC_BASE_URL=https://<your-project>.vercel.app` in Vercel so `/auth/info`
+and the built-in status page advertise a fixed deployment URL instead of deriving it
+from incoming request headers.
+
+MCP endpoint check:
+
+```bash
+MCP_TEST_BASE_URL=https://<your-project>.vercel.app \
+MCP_TEST_BEARER_TOKEN=<token-if-using-bearer> \
+npm run test:http
+```
+
+If using Clerk auth, provide a valid Clerk JWT in:
+
+- `MCP_TEST_AUTH_HEADER='Authorization: Bearer <clerk-jwt>'`
+
+## 6. Public Repo Security Checklist
+
+Treat this as required before making the repo public.
+
+1. Never commit secrets
+
+- Keep `.env` local only (already gitignored).
+- Never commit Vercel env exports.
+- Never paste real keys in README, issues, or PR comments.
+
+2. Assume key leakage can happen
+
+- Rotate leaked keys immediately in Portkey/Clerk/Redis.
+- Prefer short-lived or scoped credentials where supported.
+
+3. Keep auth enabled in production
+
+- Do not run `MCP_AUTH_MODE=none` in hosted environments.
+- Do not set `MCP_ALLOW_UNAUTHENTICATED_HTTP=true` in hosted environments.
+
+4. Restrict origins
+
+- Set exact domains in `ALLOWED_ORIGINS`.
+- Avoid `*` except temporary local debugging.
+
+5. Use least-privilege Portkey API scopes
+
+- Only grant scopes this server actually needs for your workflows.
+
+6. Isolate Redis
+
+- Require TLS (`rediss://`) and an ACL user limited to the configured replay and
+  rate-limit prefixes.
+- Use a dedicated namespace and credentials per environment.
+- Keep `MCP_EVENT_TTL_SECONDS` short; the default is 300 seconds.
+
+7. Enable repository protections
+
+- Enable GitHub secret scanning and push protection.
+- Require PR reviews before merge to `main`.
+
+8. Keep dependencies current
+
+- Run `npm audit` regularly.
+- Patch `jose`, `express`, and `redis` updates promptly.
+
+## 7. Limits and Expected Behavior
+
+- Some Portkey endpoints can still return `403 AB03` if key scopes are missing.
+- Vercel Functions are request-duration constrained; this repo sets `maxDuration` in `vercel.json`.
+- WebSockets are not required for this server; use Streamable HTTP/SSE.
+
+## 8. Team Operations
+
+For team access:
+
+- Use one shared Vercel project per environment (`staging`, `production`).
+- Manage secrets in Vercel project envs, not in local files.
+- Keep each environment on a separate Portkey key and Redis namespace.
+
+Suggested naming convention:
+
+- `MCP_REDIS_KEY_PREFIX=portkey-admin-mcp:prod`
+- `MCP_REDIS_KEY_PREFIX=portkey-admin-mcp:staging`

package/package.json

@@ -11,7 +11,7 @@
 		"lint": "biome lint .",
 		"format": "biome format --write .",
 		"check": "biome check --write .",
-		"test": "tsx --test tests/config.test.ts tests/security.test.ts tests/contract.test.ts tests/contract-extended.test.ts tests/unit.test.ts tests/http-server.test.ts tests/tools-observability.test.ts tests/tools-catalog.test.ts tests/tools-platform.test.ts tests/auth-clerk.test.ts",
+		"test": "tsx --test tests/config.test.ts tests/security.test.ts tests/contract.test.ts tests/contract-extended.test.ts tests/unit.test.ts tests/http-server.test.ts tests/tools-observability.test.ts tests/tools-catalog.test.ts tests/tools-platform.test.ts tests/current-api.test.ts tests/release-readiness.test.ts tests/auth-clerk.test.ts",
 		"dev": "tsx --watch src/index.ts",
 		"dev:http": "tsx --watch src/server.ts",
 		"smoke": "tsx tests/smoke.ts",
@@ -20,12 +20,14 @@
 		"test:contract": "tsx --test tests/contract.test.ts",
 		"test:redis": "tsx --test tests/redis-integration.test.ts",
 		"record:fixtures": "tsx tests/fixtures/record.ts",
+		"verify:tool-quality": "node scripts/check-tool-definition-quality.mjs",
 		"verify:readme-tools": "node scripts/verify-readme-tools.mjs",
 		"knip": "knip",
-		"ci": "npm run lint && npm run knip && npm run typecheck && npm run typecheck:tests && npm run test && npm run build && npm run test:e2e && npm run verify:readme-tools",
+		"ci": "npm run lint && npm run knip && npm run typecheck && npm run typecheck:tests && npm run test && npm run build && npm run verify:tool-quality && npm run test:e2e && npm run verify:readme-tools",
 		"start:http": "node build/server.js",
 		"generate:lobehub-tools": "npm run build && node scripts/generate-lobehub-tools.mjs && biome format --write lhm.plugin.json",
-		"publish:lobehub": "npm run generate:lobehub-tools && npx -y @lobehub/market-cli plugin publish --dir \"$PWD\"",
+		"update:lobehub": "npm run generate:lobehub-tools && npx -y @lobehub/market-cli plugin update --dir \"$PWD\"",
+		"publish:lobehub": "npm run update:lobehub",
 		"prepare": "[ -n \"$CI\" ] || [ -f /.dockerenv ] || [ ! -d .git ] || lefthook install",
 		"prepublishOnly": "npm run ci"
 	},
@@ -34,7 +36,10 @@
 	},
 	"packageManager": "npm@12.0.2",
 	"files": [
-		"build"
+		"build",
+		"ENDPOINTS.md",
+		"docs/PRISMA_AIRS_INTEROPERABILITY.md",
+		"docs/VERCEL_DEPLOYMENT.md"
 	],
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.30.0",
@@ -48,7 +53,7 @@
 	},
 	"name": "portkey-admin-mcp",
 	"mcpName": "io.github.CodesWhat/portkey-admin-mcp",
-	"version": "0.6.2",
+	"version": "0.7.0",
 	"main": "build/index.js",
 	"keywords": [
 		"mcp",
@@ -61,11 +66,13 @@
 		"prompts",
 		"observability",
 		"gateway",
+		"prisma-airs",
+		"palo-alto-networks",
 		"anthropic"
 	],
 	"author": "Scott Benson",
 	"license": "MIT",
-	"description": "Full Portkey Admin API MCP server",
+	"description": "Portkey Admin API MCP server with current control-plane coverage and Prisma AIRS interoperability guidance",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/CodesWhat/portkey-admin-mcp.git"