portkey-admin-mcp 0.12.2 → 0.13.0

package/ENDPOINTS.md

@@ -6,7 +6,7 @@ Route mappings were reviewed against the official Portkey OpenAPI on 2026-09-08.
 - Base URL: `https://api.portkey.ai/v1`
 - Authentication: `x-portkey-api-key`
 - Public catalog exception: `get_model_pricing` uses `https://api.portkey.ai` without authentication
-- Total: 181 tools across 20 domains
+- Total: 184 tools across 20 domains
 - Enterprise-gated names and counts are maintained in `src/tools/index.ts` and verified against README by `npm run verify:readme-tools`
 
 The route lists are domain-level service routes. The tool tables are the complete
@@ -14,6 +14,9 @@ MCP catalog and preserve the actual selection guidance exposed through
 `tools/list`. A tool can perform a workflow across several listed routes rather
 than mapping one-to-one to one HTTP endpoint.
 
+Routes marked "undocumented upstream" are called by this server but are not in
+the public Portkey OpenAPI, so their contracts can change without a spec diff.
+
 ## Workflow-only and multi-request tools
 
 | Tool | Behavior |
@@ -50,6 +53,9 @@ than mapping one-to-one to one HTTP endpoint.
 | `get_analytics_group_models` | GET `/analytics/groups/ai-models` |
 | `get_analytics_group_metadata` | GET `/analytics/groups/metadata/{key}` |
 | `get_analytics_group_providers` | GET `/analytics/groups/provider` |
+| `get_analytics_group_mcp` | GET `/analytics/groups/mcp` |
+| `get_analytics_group_a2a` | GET `/analytics/groups/a2a` |
+| `get_analytics_group_workspaces` | GET `/analytics/groups/workspaces` |
 
 <!-- tool-catalog:start -->
 ## users (10)
@@ -79,7 +85,7 @@ Routes:
 
 - GET/POST `/admin/workspaces`; GET/PUT/DELETE `/admin/workspaces/{workspaceId}`
 - GET/POST `/admin/workspaces/{workspaceId}/users`; GET/PUT/DELETE `/admin/workspaces/{workspaceId}/users/{userId}`
-- GET/POST `/scim/workspaces`; DELETE `/scim/workspaces/{mappingId}`; GET `/scim/groups`
+- GET/POST `/scim/workspaces`; DELETE `/scim/workspaces/{mappingId}`; GET `/scim/groups` (undocumented upstream; served from the `/v2` base)
 
 | Tool | Selection guidance and result |
 |---|---|
@@ -118,6 +124,7 @@ Routes:
 Routes:
 
 - GET/POST `/deployments`; GET/PUT/DELETE `/deployments/{id}`. DELETE archives; deprecated `/ping` is intentionally omitted.
+- Undocumented upstream: these tools call the `/v2` base (the `/v1` base with its suffix swapped to `/v2`), while the public OpenAPI lists `/deployments` under `/v1`.
 
 | Tool | Selection guidance and result |
 |---|---|
@@ -156,9 +163,9 @@ Routes:
 
 | Tool | Selection guidance and result |
 |---|---|
-| `list_collections` | List prompt collections in the workspace, optionally filtering by name or workspace. Returns ids, names, slugs, and timestamps so you can choose a collection_id before create_prompt, get_collection, or list_prompts. |
-| `create_collection` | Create a new prompt collection for organizing prompts by app. Use this when you need a new namespace before create_prompt; returns the collection id and slug, and does not move any prompts. |
-| `get_collection` | Fetch one collection by id or slug and return its name, slug, workspace, and timestamps. Use list_collections when browsing and get_collection when you already know the target. |
+| `list_collections` | List prompt collections in the workspace, optionally filtering by name or workspace. Returns ids, names, slugs, parent collection ids, and timestamps so you can choose a collection_id before create_prompt, get_collection, or list_prompts. |
+| `create_collection` | Create a new prompt collection for organizing prompts by app. Use this when you need a new namespace before create_prompt; set parent_collection_id to nest it under an existing collection. Returns the collection id and slug, and does not move any prompts. |
+| `get_collection` | Fetch one collection by id or slug and return its name, slug, workspace, parent collection id, child collections with prompt counts, and timestamps. Use list_collections when browsing and get_collection when you already know the target. |
 | `update_collection` | Update a collection's name or description only. This does not move prompts or change membership, so use it for metadata changes rather than reorganization. |
 | `delete_collection` | Delete a prompt collection by ID. This cannot be undone; prompts stay in the workspace but lose their collection grouping, so reassign them first if organization matters. |
 
@@ -187,7 +194,7 @@ Routes:
 | `get_prompt_version` | Retrieve a specific prompt version by its version UUID. Use list_prompt_versions to find the id first; returns the template, parameters, and model config for that version. |
 | `update_prompt_version` | Update a specific prompt version's label assignment. This only assigns or removes a label, and null clears the label after you look up ids with list_prompt_labels. |
 
-## analytics (22)
+## analytics (25)
 
 Routes:
 
@@ -209,6 +216,9 @@ Routes:
 | `get_analytics_group_models` | Get a paginated per-model breakdown with total_groups, group_count, and a models array containing request count, cost, and token usage. Use this to compare model cost, popularity, and efficiency; use get_token_analytics or get_cost_analytics for time-series trends instead. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
 | `get_analytics_group_providers` | Enterprise-gated. Get provider-grouped analytics for one workspace and time range with selectable metrics, ordering, pagination, and optional total count. Use this when comparing provider traffic or reliability; requested metric fields are preserved in each provider row. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
 | `get_analytics_group_metadata` | Get a paginated metadata breakdown with total_groups, group_count, and a metadata_groups array grouped by the required metadata_key. Use this for custom breakdowns like per-environment or per-feature analysis; pass metadata_key in addition to the time window. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
+| `get_analytics_group_mcp` | Get a paginated per-MCP-server breakdown with total_groups, group_count, and an mcp_servers array containing each server name and its request count. Use this to see which MCP servers receive the most traffic; use get_analytics_group_a2a for A2A agents or get_analytics_group_users and get_analytics_group_models for other breakdowns. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
+| `get_analytics_group_a2a` | Get a paginated per-agent breakdown with total_groups, group_count, and an agents array containing each A2A (agent-to-agent) agent name and its request count. Use this to see which agents receive the most traffic; use get_analytics_group_mcp for MCP servers instead. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
+| `get_analytics_group_workspaces` | Get a paginated per-workspace breakdown with total_groups, group_count, is_quota_exceeded when reported, and a workspaces array containing each workspace_slug with request count and cost. Use this for org-wide chargeback or comparing workspaces; pass workspace_slug to other analytics tools to drill into one workspace. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
 | `get_error_stacks_analytics` | Get stacked error-series data grouped by HTTP status code over time, with summary and per-code series. Use this to see which error classes dominate; use get_error_status_codes_analytics for distinct-code distribution instead. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
 | `get_error_status_codes_analytics` | Get HTTP error-code distribution time-series data with summary and per-code series. Use this to see which codes occur most often; use get_error_stacks_analytics for stacked or cumulative breakdowns. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
 | `get_user_requests_analytics` | Get per-user request-count time-series data with counts grouped by user. Use this to find heavy users and traffic concentration; use get_users_analytics for aggregate active and new user trends instead. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
@@ -222,8 +232,8 @@ Routes:
 
 Routes:
 
-- GET/PUT `/admin/organisation/defaults`
-- GET/PUT `/workspace-exclusions/{input-guardrails|output-guardrails}`
+- GET/PUT `/admin/organisation/defaults` (undocumented upstream)
+- GET/PUT `/workspace-exclusions/{input-guardrails|output-guardrails}` (undocumented upstream)
 - GET/POST `/guardrails`; GET/PUT/DELETE `/guardrails/{guardrailId}`
 - GET/PUT `/guardrails/{guardrailId}/mcp-servers`; PUT `/guardrails/{guardrailId}/mcp-servers/{mcpServerId}`
 
@@ -238,9 +248,9 @@ Routes:
 | `list_guardrails` | List guardrails in the org with id, slug, status, ownership, and optional workspace/org filters. Use this to find IDs and slugs before get_guardrail, update_guardrail, or delete_guardrail. |
 | `get_guardrail` | Fetch one guardrail by id or slug with its full checks and actions; use list_guardrails to discover ids first. Use before update_guardrail or delete_guardrail when you need the exact enforcement policy, and returns the full check and action configuration alongside status and ownership. |
 | `create_guardrail` | Create an LLM or MCP-tool guardrail. LLM guardrails require checks and actions; MCP-tool guardrails can be created first and mapped to servers afterward. The new version becomes the policy anchor for downstream use. |
-| `list_guardrail_mcp_servers` | List every MCP-server mapping for one guardrail, including the input/output phases and mapped capability IDs. Use this before replace_guardrail_mcp_servers because replacement removes every mapping omitted from its request. |
-| `replace_guardrail_mcp_servers` | Replace the complete MCP-server mapping set for one guardrail. Any existing server omitted from mcp_servers is removed, and an empty object clears all mappings. Read list_guardrail_mcp_servers first. Repeating the same complete map is safe. |
-| `upsert_guardrail_mcp_server` | Create or replace one guardrail mapping for one MCP server without changing mappings for other servers. run_on defaults to both input and output. Use list_guardrail_mcp_servers to inspect the current mapping set first. Repeating the same mapping is safe. |
+| `list_guardrail_mcp_servers` | List every MCP-server mapping for one guardrail, including the input/output phases and mapped capability IDs. Requires a guardrail with target mcp_tools. Use this before replace_guardrail_mcp_servers because replacement removes every mapping omitted from its request. |
+| `replace_guardrail_mcp_servers` | Replace the complete MCP-server mapping set for one guardrail. Requires a guardrail with target mcp_tools. Any existing server omitted from mcp_servers is removed, and an empty object clears all mappings. Read list_guardrail_mcp_servers first. Repeating the same complete map is safe. |
+| `upsert_guardrail_mcp_server` | Create or replace one guardrail mapping for one MCP server without changing mappings for other servers. Requires a guardrail with target mcp_tools. run_on defaults to both input and output. Use list_guardrail_mcp_servers to inspect the current mapping set first. Repeating the same mapping is safe. |
 | `update_guardrail` | Update a guardrail's name, checks, or actions, unlike create_guardrail which registers a new one or delete_guardrail which removes it. This creates a new version that takes effect immediately for dependent configs, so review list_guardrails first; returns the updated id, slug, and version_id. |
 | `delete_guardrail` | Delete a guardrail by id or slug. This is irreversible and removes the check from any configs that reference it, so review dependent configs first. |
 
@@ -324,7 +334,7 @@ Routes:
 Routes:
 
 - POST `/logs`; GET `/logs/{logId}`
-- GET `/logs/exports/field-restrictions`; GET/POST `/logs/exports`; GET/PUT `/logs/exports/{exportId}`
+- GET `/logs/exports/field-restrictions` (undocumented upstream); GET/POST `/logs/exports`; GET/PUT `/logs/exports/{exportId}`
 - POST `/logs/exports/{exportId}/{start|cancel}`; GET `/logs/exports/{exportId}/download`
 
 | Tool | Selection guidance and result |
@@ -379,10 +389,10 @@ Routes:
 | Tool | Selection guidance and result |
 |---|---|
 | `get_model_pricing` | Get Portkey's current public pricing configuration for one exact provider/model pair. Prices are returned in USD cents per token or provider-specific unit and may include cache, audio, image, fine-tuning, and calculation metadata. Use this read-only catalog lookup before setting integration pricing_adjustments or custom-model pricing; it does not return your negotiated integration multiplier or require Portkey authentication. |
-| `list_integrations` | List org-level AI provider connections with optional workspace or type filters. Use this to find integration slugs before model or workspace updates. Returns total plus id, name, slug, provider, status, description, workspace counts, and config summary. |
-| `create_integration` | Create an AI-provider integration that becomes the source for workspace providers. ai_provider_id identifies the backend; provider-specific fields configure Azure, Bedrock, Vertex, or custom hosts. For workspace-scoped integrations, create_default_provider controls automatic provider creation. key is write-only, but secret_mappings can resolve it or configuration fields from Secret References at runtime. pricing_adjustments apply negotiated discounts or markups to cost accounting. Use update_integration_models and update_integration_workspaces after creation; returns the new integration id and slug. |
+| `list_integrations` | List org-level AI provider connections with optional workspace, type, or tag filters. Use this to find integration slugs before model or workspace updates. Returns total plus id, name, slug, provider, status, description, workspace counts, and config summary. |
+| `create_integration` | Create an AI-provider integration that becomes the source for workspace providers. ai_provider_id identifies the backend; provider-specific fields configure Azure, Bedrock, Vertex, or custom hosts. For workspace-scoped integrations, create_default_provider controls automatic provider creation. key is write-only, but secret_mappings can resolve it or configuration fields from Secret References at runtime. pricing_adjustments apply negotiated discounts or markups to cost accounting; tags attach key-value labels that list_integrations can filter on. Use update_integration_models and update_integration_workspaces after creation; returns the new integration id and slug. |
 | `get_integration` | Fetch one integration by slug, including masked key, workspace access, allowed models, and configuration metadata. Use this before editing provider-specific settings or auditing access. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
-| `update_integration` | Update an integration's name, description, API key, provider config, Secret Reference mappings, or pricing adjustments by slug. Only provided fields change; key, secret mapping, and config changes take effect immediately and can disrupt dependent providers or live requests, while pricing multipliers change cost analytics and budget accounting. Review get_integration first. Model availability and workspace access remain separate in update_integration_models and update_integration_workspaces. |
+| `update_integration` | Update an integration's name, description, API key, provider config, Secret Reference mappings, pricing adjustments, or tags by slug. Only provided fields change; tags replaces the whole map and null clears it; key, secret mapping, and config changes take effect immediately and can disrupt dependent providers or live requests, while pricing multipliers change cost analytics and budget accounting. Review get_integration first. Model availability and workspace access remain separate in update_integration_models and update_integration_workspaces. |
 | `delete_integration` | Delete an integration by slug. This is irreversible and stops the org-level connection, which will break dependent virtual keys, providers, and workspace access. |
 | `list_integration_models` | List models enabled on an integration. Use this to verify model availability before creating prompts or configs. Returns total plus model ids, display names, enabled state, and custom-model markers. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. |
 | `update_integration_models` | Bulk enable or disable integration models, register custom or fine-tuned models, set per-model hosts and headers, and attach static token pricing. allow_all_models controls whether future provider models start enabled. These changes affect every workspace using the integration; inspect list_integration_models first and use get_model_pricing when deriving custom rates. Returns success and the number of models updated. |

package/README.md

@@ -4,7 +4,7 @@
 
 <h1>Portkey Admin MCP Server</h1>
 
-**The [Portkey](https://portkey.ai/) Admin API as an MCP server — 181 tools across prompts, configs, keys, analytics, governance, deployments, and more.**
+**The [Portkey](https://portkey.ai/) Admin API as an MCP server — 184 tools across prompts, configs, keys, analytics, governance, deployments, and more.**
 
 </div>
 
@@ -96,7 +96,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 181-tool catalog is roughly 400 KB once a
+is paginated, and the complete 184-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.
 
@@ -148,13 +148,13 @@ Then use this config:
 | **Guardrails** | 14 | LLM and MCP-tool policies, server mappings, organisation defaults, workspace exclusions |
 | **Usage Limits** | 7 | Cost and token consumption limits |
 | **Rate Limits** | 5 | Request frequency controls |
-| **Analytics** | 22 | Cost, latency, errors, tokens, cache, feedback, provider groups |
+| **Analytics** | 25 | Cost, latency, errors, tokens, cache, feedback, provider, MCP, A2A, and workspace 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 |
 
-**181 tools total across 20 tool domains.** See [ENDPOINTS.md](./ENDPOINTS.md) for the full list with descriptions.
+**184 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
@@ -172,13 +172,13 @@ If a tool returns a `403` with Portkey error `AB03`, it means missing scopes —
 <details>
 <summary><strong>Enterprise-gated tools and other scope requirements</strong></summary>
 
-### Enterprise-gated tools (53)
+### Enterprise-gated tools (56)
 
 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 (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` |
+| Analytics (25) | `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`, `get_analytics_group_mcp`, `get_analytics_group_a2a`, `get_analytics_group_workspaces` | 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` |