portkey-admin-mcp 0.10.0 → 0.11.0

package/README.md

@@ -4,25 +4,29 @@
 
 <h1>Portkey Admin MCP Server</h1>
 
-**The [Portkey](https://portkey.ai/) Admin API as an MCP server — 171 tools across prompts, configs, keys, analytics, governance, and more.**
+**The [Portkey](https://portkey.ai/) Admin API as an MCP server — 178 tools across prompts, configs, keys, analytics, governance, deployments, and more.**
 
 </div>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/portkey-admin-mcp"><img src="https://img.shields.io/npm/v/portkey-admin-mcp.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/portkey-admin-mcp"><img src="https://img.shields.io/npm/dm/portkey-admin-mcp.svg" alt="npm downloads"></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg" alt="Node.js"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
-  <br>
+</p>
+
+<p align="center">
   <a href="https://github.com/CodesWhat/portkey-admin-mcp/actions/workflows/ci.yml"><img src="https://github.com/CodesWhat/portkey-admin-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://securityscorecards.dev/viewer/?uri=github.com/CodesWhat/portkey-admin-mcp"><img src="https://img.shields.io/ossf-scorecard/github.com/CodesWhat/portkey-admin-mcp?label=openssf+scorecard&style=flat" alt="OpenSSF Scorecard"></a>
   <a href="https://www.bestpractices.dev/projects/14031"><img src="https://www.bestpractices.dev/projects/14031/badge" alt="OpenSSF Best Practices"></a>
-  <a href="https://github.com/punkpeye/awesome-mcp-servers"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome MCP Servers"></a>
-  <a href="https://lobehub.com/mcp/codeswhat-portkey-admin-mcp"><img src="https://lobehub.com/badge/mcp/codeswhat-portkey-admin-mcp" alt="LobeHub MCP"></a>
+  <a href="https://qlty.sh/gh/CodesWhat/projects/portkey-admin-mcp"><img src="https://qlty.sh/gh/CodesWhat/projects/portkey-admin-mcp/maintainability.svg" alt="Maintainability"></a>
+  <a href="https://qlty.sh/gh/CodesWhat/projects/portkey-admin-mcp"><img src="https://qlty.sh/gh/CodesWhat/projects/portkey-admin-mcp/coverage.svg" alt="Code Coverage"></a>
 </p>
 
 <p align="center">
-  <a href="https://glama.ai/mcp/servers/CodesWhat/portkey-admin-mcp"><img src="https://glama.ai/mcp/servers/CodesWhat/portkey-admin-mcp/badges/card.svg" alt="portkey-admin-mcp MCP server"></a>
+  <a href="https://www.npmjs.com/package/portkey-admin-mcp"><img src="https://img.shields.io/npm/dm/portkey-admin-mcp.svg" alt="npm downloads"></a>
+  <a href="https://github.com/punkpeye/awesome-mcp-servers"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome MCP Servers"></a>
+  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=io.github.CodesWhat/portkey-admin-mcp"><img src="https://img.shields.io/badge/MCP-Registry-blue" alt="MCP Registry"></a>
+  <a href="https://github.com/sponsors/CodesWhat"><img src="https://img.shields.io/badge/Sponsor-ea4aaa?logo=githubsponsors&logoColor=white" alt="Sponsor"></a>
 </p>
 
 <hr>
@@ -30,24 +34,25 @@
 > [!IMPORTANT]
 > **Active compatibility development.** Palo Alto Networks completed its Portkey acquisition on 2026‑05‑29 and now presents Portkey as the core of Prisma AIRS AI Gateway. The Portkey Admin API remains live, and its official OpenAPI and product changelog continued adding control-plane surfaces through August 2026; this project has therefore resumed API-coverage work. It targets the Portkey-compatible API (`x-portkey-api-key`), not Prisma AIRS/Strata Cloud Manager directly. Prisma AIRS AI Gateway currently has a different management and authentication surface, so it is not a `PORTKEY_BASE_URL` swap. See the short [Prisma AIRS interoperability guide](./docs/PRISMA_AIRS_INTEROPERABILITY.md) for the supported side-by-side model and adapter criteria.
 
-<h2 align="center">📑 Contents</h2>
-
-- [🚀 Quick Start](#quick-start)
-- [🧰 What You Can Do](#what-you-can-do)
-- [🔑 API Key Scopes](#api-key-scopes)
-- [🌐 HTTP Server (Experimental)](#http-server)
-- [🏗️ Architecture](./docs/ARCHITECTURE.md)
-- [🔄 Prisma AIRS interoperability](./docs/PRISMA_AIRS_INTEROPERABILITY.md)
-- [🔏 Verify a release](./docs/VERIFY_RELEASE.md)
-- [🛠️ Development](#development)
-- [🤝 Contributing](./CONTRIBUTING.md)
-- [🏛️ Governance](./GOVERNANCE.md)
-- [🛡️ Security assurance](./SECURITY-ASSURANCE.md)
-- [🧾 Full tool list — ENDPOINTS.md](./ENDPOINTS.md)
+<h2 align="center">Contents</h2>
+
+- [Quick Start](#quick-start)
+- [What You Can Do](#what-you-can-do)
+- [API Key Scopes](#api-key-scopes)
+- [HTTP Server (Experimental)](#http-server)
+- [Architecture](./docs/ARCHITECTURE.md)
+- [Prisma AIRS interoperability](./docs/PRISMA_AIRS_INTEROPERABILITY.md)
+- [Verify a release](./docs/VERIFY_RELEASE.md)
+- [Development](#development)
+- [Community](#community)
+- [Contributing](./CONTRIBUTING.md)
+- [Governance](./GOVERNANCE.md)
+- [Security assurance](./SECURITY-ASSURANCE.md)
+- [Full tool list — ENDPOINTS.md](./ENDPOINTS.md)
 
 <hr>
 
-<h2 align="center" id="quick-start">🚀 Quick Start</h2>
+<h2 align="center" id="quick-start">Quick Start</h2>
 
 You need a **Portkey API key** with appropriate scopes. Get one from your [Portkey dashboard](https://app.portkey.ai/) under API Keys.
 
@@ -90,7 +95,7 @@ npx -y portkey-admin-mcp
 ```
 
 Scoping domains is also the biggest lever on context cost, not just access. `tools/list`
-is paginated, and the complete 171-tool catalog is roughly 387 KB (~99K tokens) once a
+is paginated, and the complete 178-tool catalog is roughly 400 KB once a
 client follows `nextCursor` through every page. Narrowing to the domains a client
 actually needs cuts that roughly proportionally.
 
@@ -122,7 +127,7 @@ Then use this config:
 
 <hr>
 
-<h2 align="center" id="what-you-can-do">🧰 What You Can Do</h2>
+<h2 align="center" id="what-you-can-do">What You Can Do</h2>
 
 | Category | Tools | Examples |
 |----------|-------|---------|
@@ -130,6 +135,7 @@ Then use this config:
 | **Prompt Partials** | 7 | Reusable prompt fragments with versioning |
 | **Prompt Labels** | 5 | Organize prompt versions (production, staging, dev) |
 | **Configs** | 6 | Gateway routing, caching, retry, loadbalancing |
+| **Deployments** | 5 | Register, inspect, update, and archive self-hosted Gateways |
 | **API Keys** | 6 | Create, rotate, and manage scoped API keys |
 | **Secret References** | 5 | Manage AWS, Azure, and HashiCorp external-secret references |
 | **Virtual Keys** | 5 | Manage provider access keys |
@@ -141,30 +147,42 @@ Then use this config:
 | **Guardrails** | 11 | Content safety policies, organisation defaults, workspace exclusions |
 | **Usage Limits** | 7 | Cost and token consumption limits |
 | **Rate Limits** | 5 | Request frequency controls |
-| **Analytics** | 20 | Cost, latency, errors, tokens, cache, feedback |
+| **Analytics** | 22 | Cost, latency, errors, tokens, cache, feedback, provider groups |
 | **Logging** | 10 | Log retrieval, ingestion, export, and field restrictions |
 | **Tracing** | 2 | Feedback creation and updates on traces |
 | **Users & Workspaces** | 24 | User management, invites, workspace members, SCIM group mappings |
 | **Audit** | 1 | Audit log access |
 
-**171 tools total.** See [ENDPOINTS.md](./ENDPOINTS.md) for the full list with descriptions.
+**178 tools total across 20 tool domains.** See [ENDPOINTS.md](./ENDPOINTS.md) for the full list with descriptions.
+
+Portkey's newer product language increasingly presents provider credentials as
+Providers, while the current Admin API still exposes both `/virtual-keys` and
+`/providers`. This server keeps both domains: Virtual Keys manage provider access
+credentials, and Providers manage workspace provider configurations.
 
 <hr>
 
-<h2 align="center" id="api-key-scopes">🔑 API Key Scopes</h2>
+<h2 align="center" id="api-key-scopes">API Key Scopes</h2>
 
 Most tools work with a **workspace-scoped service key** that has Select All permissions enabled. That covers prompts, configs, virtual/API keys, providers, guardrails, workspace integrations, MCP servers, rate/usage limits, logs, prompt completions, and workspace user management.
 
-### Enterprise-gated tools (40)
+If a tool returns a `403` with Portkey error `AB03`, it means missing scopes — not a broken endpoint.
+
+<details>
+<summary><strong>Enterprise-gated tools and other scope requirements</strong></summary>
+
+### Enterprise-gated tools (53)
 
 The following tools require an **organisation-level scope that is only available on Portkey Enterprise plans**. They return `403 You do not have enough permissions to execute this request` on workspace plans. Their descriptions include an `Enterprise-gated. Returns 403 on non-Enterprise Portkey plans.` suffix so MCP clients know upfront.
 
 | Area | Tools | Required scope |
 |---|---|---|
-| Analytics (20) | `get_cost_analytics`, `get_request_analytics`, `get_token_analytics`, `get_latency_analytics`, `get_error_analytics`, `get_error_rate_analytics`, `get_cache_hit_latency`, `get_cache_hit_rate`, `get_users_analytics`, `get_error_stacks_analytics`, `get_error_status_codes_analytics`, `get_user_requests_analytics`, `get_rescued_requests_analytics`, `get_feedback_analytics`, `get_feedback_models_analytics`, `get_feedback_scores_analytics`, `get_feedback_weighted_analytics`, `get_analytics_group_users`, `get_analytics_group_models`, `get_analytics_group_metadata` | org-level `analytics.view` |
+| Analytics (22) | `get_cost_analytics`, `get_request_analytics`, `get_token_analytics`, `get_latency_analytics`, `get_error_analytics`, `get_error_rate_analytics`, `get_cache_hit_latency`, `get_cache_hit_rate`, `get_cache_summary`, `get_users_analytics`, `get_error_stacks_analytics`, `get_error_status_codes_analytics`, `get_user_requests_analytics`, `get_rescued_requests_analytics`, `get_feedback_analytics`, `get_feedback_models_analytics`, `get_feedback_scores_analytics`, `get_feedback_weighted_analytics`, `get_analytics_group_users`, `get_analytics_group_models`, `get_analytics_group_metadata`, `get_analytics_group_providers` | org-level `analytics.view` |
+| Deployments (5) | `list_deployments`, `register_deployment`, `get_deployment`, `update_deployment`, `archive_deployment` | Enterprise deployment administration |
 | Audit | `list_audit_logs` | `audit_logs.list` |
 | Org-level integrations | `get_integration`, `list_integration_models`, `list_integration_workspaces` | `organisation_integrations.read` |
 | Org-level users | `list_all_users`, `get_user`, `get_user_stats`, `list_user_invites` | `organisation_users.list` / `organisation_users.read` |
+| Organisation guardrails (6) | `get_organisation_defaults`, `update_organisation_defaults`, `list_input_guardrail_workspace_exclusions`, `update_input_guardrail_workspace_exclusions`, `list_output_guardrail_workspace_exclusions`, `update_output_guardrail_workspace_exclusions` | `organisation_settings.read/update` and `organisation_exclusions.list/update` |
 | Log exports (8) | `create_log_export`, `list_log_exports`, `get_log_export`, `start_log_export`, `cancel_log_export`, `download_log_export`, `update_log_export`, `get_log_export_field_restrictions` | Enterprise Logs Export + `logs.export` |
 | SCIM groups (4) | `list_scim_groups`, `list_scim_workspace_mappings`, `create_scim_workspace_mapping`, `delete_scim_workspace_mapping` | SCIM enabled + organisation admin access |
 
@@ -175,16 +193,22 @@ The following tools require an **organisation-level scope that is only available
 | Prompt completions (`run_prompt_completion`) | `completions.write` scope + billing metadata (`app`, `env`) |
 | Org-level service API key creation via `create_api_key` | `organisation_service_api_keys.create` (Enterprise) |
 
-If a tool returns a `403` with Portkey error `AB03`, it means missing scopes — not a broken endpoint.
+</details>
 
 <hr>
 
-<h2 align="center" id="http-server">🌐 HTTP Server (Experimental)</h2>
+<h2 align="center" id="http-server">HTTP Server (Experimental)</h2>
 
 > **Status**: The HTTP transport works locally and is covered by the integration test suite, but it is a proof of concept — there is **no hosted version** of this server, and hosted deployment is not currently a goal. Use stdio (npx) as the supported transport.
 
 The server supports Streamable HTTP for remote access:
 
+HTTP authentication controls access to the server, but it does not impersonate
+separate Portkey tenants. All authenticated principals use the same configured
+`PORTKEY_API_KEY` and can invoke any enabled tool and scope that credential
+grants. Run separate instances or deployments with separately scoped Portkey
+credentials and `PORTKEY_TOOL_DOMAINS` allowlists for different trust levels.
+
 ```bash
 PORTKEY_API_KEY=your_key \
 MCP_HOST=127.0.0.1 \
@@ -203,7 +227,8 @@ PORTKEY_API_KEY=your_key MCP_AUTH_MODE=bearer MCP_AUTH_TOKEN=your_secret \
 
 For local-only HTTP use, leave `MCP_HOST` at its default `127.0.0.1`. Set `MCP_HOST=0.0.0.0` only when you intentionally need to accept connections from outside the local machine, such as Docker or a reverse proxy on another interface.
 
-### Configuration
+<details>
+<summary><strong>Full environment variable reference</strong></summary>
 
 | Variable | Default | Description |
 |----------|---------|-------------|
@@ -211,7 +236,7 @@ For local-only HTTP use, leave `MCP_HOST` at its default `127.0.0.1`. Set `MCP_H
 | `PORTKEY_BASE_URL` | `https://api.portkey.ai/v1` | Portkey Admin API base URL. Prisma AIRS/SCM URLs are not compatible; credentialed requests never auto-follow redirects |
 | `PORTKEY_ALLOW_PRIVATE_BASE_URL` | — | Set to `true` to allow a literal loopback/private `PORTKEY_BASE_URL` |
 | `PORTKEY_ALLOW_INSECURE_HTTP` | — | Separately set to `true` only when a trusted self-hosted gateway cannot use HTTPS |
-| `PORTKEY_TOOL_DOMAINS` | — | Server-side tool-domain allowlist. HTTP `?tools=` may narrow this set but cannot expand it |
+| `PORTKEY_TOOL_DOMAINS` | — | Server-side allowlist of the 20 domains: `users`, `workspaces`, `configs`, `deployments`, `keys`, `collections`, `prompts`, `analytics`, `guardrails`, `limits`, `audit`, `labels`, `partials`, `tracing`, `logging`, `providers`, `secret-references`, `integrations`, `mcp-integrations`, `mcp-servers`. HTTP `?tools=` may narrow it but cannot expand it |
 | `MCP_HOST` | `127.0.0.1` | Bind address |
 | `MCP_PORT` | `3000` | Port |
 | `MCP_PUBLIC_BASE_URL` | — | Public absolute base URL to advertise from `/auth/info` and the status page; recommended for hosted deployments |
@@ -226,6 +251,8 @@ For local-only HTTP use, leave `MCP_HOST` at its default `127.0.0.1`. Set `MCP_H
 | `MCP_MAX_SESSIONS` | `100` | Maximum concurrent stateful sessions or active stateless request handlers |
 | `MCP_EVENT_STORE` | `off` | `off`, `memory`, or `redis`; stateless `GET /mcp` replay requires `memory` or `redis` |
 | `MCP_EVENT_TTL_SECONDS` | `300` | Replay retention in seconds |
+| `MCP_EVENT_STORE_MAX_EVENTS` | `10000` | Maximum events retained by the in-memory replay store; oldest events are evicted first |
+| `MCP_EVENT_STORE_MAX_BYTES` | `67108864` | Approximate maximum serialized bytes retained by the in-memory replay store |
 | `MCP_EVENT_STORE_COMMAND_TIMEOUT_MS` | `5000` | Redis command timeout for the event store, in milliseconds; `0` disables the timeout (restores unbounded pre-v6 behavior) |
 | `MCP_REDIS_URL` | — | Redis URL for shared event store; production requires `rediss://` and ACL-scoped credentials |
 | `MCP_EVENT_ENCRYPTION_KEY` | — | Required 32-byte base64 AES key for Redis replay payloads; generate with `openssl rand -base64 32` |
@@ -233,7 +260,7 @@ For local-only HTTP use, leave `MCP_HOST` at its default `127.0.0.1`. Set `MCP_H
 | `MCP_TLS_KEY_PATH` | — | TLS key for native HTTPS |
 | `MCP_TLS_CERT_PATH` | — | TLS cert for native HTTPS |
 | `ALLOWED_ORIGINS` | — | CORS allow-list; also used to validate the `Host` header (DNS-rebinding protection) when `MCP_AUTH_MODE=none` |
-| `MCP_TRUST_PROXY` | `false` | Trust proxy headers (for reverse proxies) |
+| `MCP_TRUST_PROXY` | `loopback` | Express trust-proxy policy. Use an exact nonnegative hop count or trusted proxy subnet; `true` is rejected because it trusts forwarding headers from every peer |
 | `RATE_LIMIT_STORE` | `memory` | `redis` for multi-instance/serverless deployments; production memory mode requires `RATE_LIMIT_SINGLE_PROCESS=true` |
 | `RATE_LIMIT_REDIS_URL` | — | Shared limiter Redis URL, falling back to `MCP_REDIS_URL`/`REDIS_URL`; production requires `rediss://` |
 | `RATE_LIMIT_REDIS_KEY_PREFIX` | `mcp:rate-limit` | Redis namespace for atomic pre-authentication IP and principal-plus-IP token buckets |
@@ -243,6 +270,8 @@ Production containers must choose their rate-limit topology explicitly: set
 `RATE_LIMIT_STORE=redis` for multi-instance deployments, or set
 `RATE_LIMIT_SINGLE_PROCESS=true` only for a single long-lived process.
 
+</details>
+
 <details>
 <summary><strong>Vercel deployment</strong></summary>
 
@@ -285,7 +314,7 @@ docker run \
 
 <hr>
 
-<h2 align="center" id="development">🛠️ Development</h2>
+<h2 align="center" id="development">Development</h2>
 
 ```bash
 npm run dev           # stdio with hot reload
@@ -294,12 +323,17 @@ npm test              # unit + contract tests
 npm run test:coverage # unit + contract tests with the enforced 80% line floor
 npm run test:e2e      # MCP protocol tests
 npm run test:http     # HTTP endpoint smoke test
+npm run smoke         # credentialed read-only Portkey API smoke suite
 npm run ci            # full pipeline (lint + typecheck + coverage + build + e2e + verify)
 ```
 
+The live smoke suite reports expected credential-scope denials and the explicitly
+tracked hosted control-plane route gaps as skips. Unexpected HTTP responses,
+network errors, and response-contract failures still fail the run.
+
 The required CI and release gates measure every TypeScript source file and fail
-below 80% line coverage. The current full report is 99.36% lines, 92.61%
-branches, and 99.01% functions.
+below 80% line coverage. The current full report is 98.19% lines, 91.92%
+branches, and 98.58% functions.
 
 `npm run dev:http` now requires `MCP_AUTH_MODE=bearer` or `MCP_AUTH_MODE=clerk` by default. For deliberate local-only unauthenticated testing, set `MCP_ALLOW_UNAUTHENTICATED_HTTP=true`.
 
@@ -309,6 +343,12 @@ documented in [`GOVERNANCE.md`](GOVERNANCE.md). Report vulnerabilities through
 [`SECURITY.md`](SECURITY.md), and see [`SECURITY-ASSURANCE.md`](SECURITY-ASSURANCE.md)
 for the public threat model and assurance case.
 
+<hr>
+
+<h2 align="center" id="community">Community</h2>
+
+Questions and bug reports belong in [Issues](https://github.com/CodesWhat/portkey-admin-mcp/issues); broader discussion, ideas, and help using the server belong in [Discussions](https://github.com/CodesWhat/portkey-admin-mcp/discussions).
+
 ---
 
 <div align="center">
@@ -336,7 +376,11 @@ for the public threat model and assurance case.
   </picture>
 </a>
 
-[![Sponsor](https://img.shields.io/badge/Sponsor-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/CodesWhat)
+Also listed on [LobeHub](https://lobehub.com/mcp/codeswhat-portkey-admin-mcp) and [Glama](https://glama.ai/mcp/servers/CodesWhat/portkey-admin-mcp):
+
+[![LobeHub MCP](https://lobehub.com/badge/mcp/codeswhat-portkey-admin-mcp)](https://lobehub.com/mcp/codeswhat-portkey-admin-mcp)
+
+<a href="https://glama.ai/mcp/servers/CodesWhat/portkey-admin-mcp"><img src="https://glama.ai/mcp/servers/CodesWhat/portkey-admin-mcp/badges/card.svg" alt="portkey-admin-mcp MCP server"></a>
 
 <a href="#portkey-admin-mcp-server">Back to top</a>