\n\n**The [Portkey](https://portkey.ai/) Admin API as an MCP server — 178 tools across prompts, configs, keys, analytics, governance, deployments, and more.**\n\n
\n\n
\n \n \n \n
\n\n
\n \n \n \n \n \n
\n\n
\n \n \n \n \n
\n\n\n\n> [!IMPORTANT]\n> **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.\n\n
Contents
\n\n- [Quick Start](#quick-start)\n- [What You Can Do](#what-you-can-do)\n- [API Key Scopes](#api-key-scopes)\n- [HTTP Server (Experimental)](#http-server)\n- [Architecture](./docs/ARCHITECTURE.md)\n- [Prisma AIRS interoperability](./docs/PRISMA_AIRS_INTEROPERABILITY.md)\n- [Verify a release](./docs/VERIFY_RELEASE.md)\n- [Development](#development)\n- [Community](#community)\n- [Contributing](./CONTRIBUTING.md)\n- [Governance](./GOVERNANCE.md)\n- [Security assurance](./SECURITY-ASSURANCE.md)\n- [Full tool list — ENDPOINTS.md](./ENDPOINTS.md)\n\n\n\n
Quick Start
\n\nYou need a **Portkey API key** with appropriate scopes. Get one from your [Portkey dashboard](https://app.portkey.ai/) under API Keys.\n\n### Claude Code\n\n```bash\nclaude mcp add -e PORTKEY_API_KEY=your_key portkey-admin -- npx -y portkey-admin-mcp\n```\n\n### Cursor / Windsurf / VS Code\n\nAdd to your MCP config (`.cursor/mcp.json`, `.windsurf/mcp.json`, or `.vscode/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"portkey-admin\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"portkey-admin-mcp\"],\n \"env\": {\n \"PORTKEY_API_KEY\": \"your_api_key\"\n }\n }\n }\n}\n```\n\n### Run directly\n\n```bash\nPORTKEY_API_KEY=your_key npx -y portkey-admin-mcp\n```\n\nTo expose only a focused subset of tools in stdio clients, set `PORTKEY_TOOL_DOMAINS`:\n\n```bash\nPORTKEY_API_KEY=your_key \\\nPORTKEY_TOOL_DOMAINS=prompts,analytics \\\nnpx -y portkey-admin-mcp\n```\n\nScoping domains is also the biggest lever on context cost, not just access. `tools/list`\nis paginated, and the complete 178-tool catalog is roughly 400 KB once a\nclient follows `nextCursor` through every page. Narrowing to the domains a client\nactually needs cuts that roughly proportionally.\n\n\nBuild from source\n\n```bash\ngit clone https://github.com/CodesWhat/portkey-admin-mcp.git\ncd portkey-admin-mcp\nnpm install && npm run build\n```\n\nThen use this config:\n```json\n{\n \"mcpServers\": {\n \"portkey-admin\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/portkey-admin-mcp/build/index.js\"],\n \"env\": {\n \"PORTKEY_API_KEY\": \"your_api_key\"\n }\n }\n }\n}\n```\n\n\n\n\n\n
What You Can Do
\n\n| Category | Tools | Examples |\n|----------|-------|---------|\n| **Prompts** | 14 | Create, version, render, execute, migrate, promote prompts |\n| **Prompt Partials** | 7 | Reusable prompt fragments with versioning |\n| **Prompt Labels** | 5 | Organize prompt versions (production, staging, dev) |\n| **Configs** | 6 | Gateway routing, caching, retry, loadbalancing |\n| **Deployments** | 5 | Register, inspect, update, and archive self-hosted Gateways |\n| **API Keys** | 6 | Create, rotate, and manage scoped API keys |\n| **Secret References** | 5 | Manage AWS, Azure, and HashiCorp external-secret references |\n| **Virtual Keys** | 5 | Manage provider access keys |\n| **Collections** | 5 | Group prompts by app or project |\n| **Providers** | 5 | Manage AI provider configurations |\n| **Integrations** | 11 | Provider integrations, model pricing, models, workspace access |\n| **MCP Integrations** | 10 | External MCP tool integrations |\n| **MCP Servers** | 12 | MCP server registry, capabilities, and live connections |\n| **Guardrails** | 11 | Content safety policies, organisation defaults, workspace exclusions |\n| **Usage Limits** | 7 | Cost and token consumption limits |\n| **Rate Limits** | 5 | Request frequency controls |\n| **Analytics** | 22 | Cost, latency, errors, tokens, cache, feedback, provider groups |\n| **Logging** | 10 | Log retrieval, ingestion, export, and field restrictions |\n| **Tracing** | 2 | Feedback creation and updates on traces |\n| **Users & Workspaces** | 24 | User management, invites, workspace members, SCIM group mappings |\n| **Audit** | 1 | Audit log access |\n\n**178 tools total across 20 tool domains.** See [ENDPOINTS.md](./ENDPOINTS.md) for the full list with descriptions.\n\nPortkey's newer product language increasingly presents provider credentials as\nProviders, while the current Admin API still exposes both `/virtual-keys` and\n`/providers`. This server keeps both domains: Virtual Keys manage provider access\ncredentials, and Providers manage workspace provider configurations.\n\n\n\n
API Key Scopes
\n\nMost 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.\n\nIf a tool returns a `403` with Portkey error `AB03`, it means missing scopes — not a broken endpoint.\n\n\nEnterprise-gated tools and other scope requirements\n\n### Enterprise-gated tools (53)\n\nThe 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.\n\n| Area | Tools | Required scope |\n|---|---|---|\n| 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` |\n| Deployments (5) | `list_deployments`, `register_deployment`, `get_deployment`, `update_deployment`, `archive_deployment` | Enterprise deployment administration |\n| Audit | `list_audit_logs` | `audit_logs.list` |\n| Org-level integrations | `get_integration`, `list_integration_models`, `list_integration_workspaces` | `organisation_integrations.read` |\n| Org-level users | `list_all_users`, `get_user`, `get_user_stats`, `list_user_invites` | `organisation_users.list` / `organisation_users.read` |\n| 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` |\n| 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` |\n| SCIM groups (4) | `list_scim_groups`, `list_scim_workspace_mappings`, `create_scim_workspace_mapping`, `delete_scim_workspace_mapping` | SCIM enabled + organisation admin access |\n\n### Other scope requirements\n\n| Feature | Required |\n|---------|----------|\n| Prompt completions (`run_prompt_completion`) | `completions.write` scope + billing metadata (`app`, `env`) |\n| Org-level service API key creation via `create_api_key` | `organisation_service_api_keys.create` (Enterprise) |\n\n\n\n\n\n
HTTP Server (Experimental)
\n\n> **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.\n\nThe server supports Streamable HTTP for remote access:\n\nHTTP authentication controls access to the server, but it does not impersonate\nseparate Portkey tenants. All authenticated principals use the same configured\n`PORTKEY_API_KEY` and can invoke any enabled tool and scope that credential\ngrants. Run separate instances or deployments with separately scoped Portkey\ncredentials and `PORTKEY_TOOL_DOMAINS` allowlists for different trust levels.\n\n```bash\nPORTKEY_API_KEY=your_key \\\nMCP_HOST=127.0.0.1 \\\nMCP_PORT=3000 \\\nMCP_PUBLIC_BASE_URL=https://mcp.example.com \\\nMCP_AUTH_MODE=bearer \\\nMCP_AUTH_TOKEN=your_secret \\\nnode build/server.js\n```\n\nOr via npx (the `portkey-admin-mcp` package includes the HTTP binary):\n```bash\nPORTKEY_API_KEY=your_key MCP_AUTH_MODE=bearer MCP_AUTH_TOKEN=your_secret \\\n npx -y -p portkey-admin-mcp portkey-admin-mcp-http\n```\n\nFor 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.\n\n\nFull environment variable reference\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORTKEY_API_KEY` | (required) | Your Portkey API key |\n| `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 |\n| `PORTKEY_ALLOW_PRIVATE_BASE_URL` | — | Set to `true` to allow a literal loopback/private `PORTKEY_BASE_URL` |\n| `PORTKEY_ALLOW_INSECURE_HTTP` | — | Separately set to `true` only when a trusted self-hosted gateway cannot use HTTPS |\n| `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 |\n| `MCP_HOST` | `127.0.0.1` | Bind address |\n| `MCP_PORT` | `3000` | Port |\n| `MCP_PUBLIC_BASE_URL` | — | Public absolute base URL to advertise from `/auth/info` and the status page; recommended for hosted deployments |\n| `MCP_AUTH_MODE` | `none` | `none`, `bearer`, or `clerk` (`none` is blocked for HTTP unless explicitly overridden) |\n| `MCP_AUTH_TOKEN` | — | Secret for bearer auth |\n| `CLERK_ISSUER` / `CLERK_AUDIENCE` | — | Required issuer and audience when `MCP_AUTH_MODE=clerk` |\n| `CLERK_ALLOWED_SUBJECTS` | — | Optional CSV subject allowlist for Clerk; at least one Clerk authorization policy is required |\n| `CLERK_ALLOWED_ORGANIZATION_IDS` / `CLERK_ALLOWED_ROLES` | — | Optional CSV organization and role constraints; every configured constraint must match |\n| `CLERK_REQUIRED_PERMISSIONS` | — | Optional CSV permissions that must all be present in the verified Clerk JWT |\n| `MCP_ALLOW_UNAUTHENTICATED_HTTP` | — | Set to `true` only for intentional local unauthenticated HTTP debugging |\n| `MCP_SESSION_MODE` | `stateful` | `stateful` or `stateless` |\n| `MCP_MAX_SESSIONS` | `100` | Maximum concurrent stateful sessions or active stateless request handlers |\n| `MCP_EVENT_STORE` | `off` | `off`, `memory`, or `redis`; stateless `GET /mcp` replay requires `memory` or `redis` |\n| `MCP_EVENT_TTL_SECONDS` | `300` | Replay retention in seconds |\n| `MCP_EVENT_STORE_MAX_EVENTS` | `10000` | Maximum events retained by the in-memory replay store; oldest events are evicted first |\n| `MCP_EVENT_STORE_MAX_BYTES` | `67108864` | Approximate maximum serialized bytes retained by the in-memory replay store |\n| `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) |\n| `MCP_REDIS_URL` | — | Redis URL for shared event store; production requires `rediss://` and ACL-scoped credentials |\n| `MCP_EVENT_ENCRYPTION_KEY` | — | Required 32-byte base64 AES key for Redis replay payloads; generate with `openssl rand -base64 32` |\n| `MCP_REDIS_KEY_PREFIX` | `mcp:event-store` | Dedicated Redis namespace for replay data |\n| `MCP_TLS_KEY_PATH` | — | TLS key for native HTTPS |\n| `MCP_TLS_CERT_PATH` | — | TLS cert for native HTTPS |\n| `ALLOWED_ORIGINS` | — | CORS allow-list; also used to validate the `Host` header (DNS-rebinding protection) when `MCP_AUTH_MODE=none` |\n| `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 |\n| `RATE_LIMIT_STORE` | `memory` | `redis` for multi-instance/serverless deployments; production memory mode requires `RATE_LIMIT_SINGLE_PROCESS=true` |\n| `RATE_LIMIT_REDIS_URL` | — | Shared limiter Redis URL, falling back to `MCP_REDIS_URL`/`REDIS_URL`; production requires `rediss://` |\n| `RATE_LIMIT_REDIS_KEY_PREFIX` | `mcp:rate-limit` | Redis namespace for atomic pre-authentication IP and principal-plus-IP token buckets |\n| `RATE_LIMIT_MAX_BUCKETS` | `10000` | Maximum local buckets in explicit memory mode before new clients share overflow capacity |\n\nProduction containers must choose their rate-limit topology explicitly: set\n`RATE_LIMIT_STORE=redis` for multi-instance deployments, or set\n`RATE_LIMIT_SINGLE_PROCESS=true` only for a single long-lived process.\n\n\n\n\nVercel deployment\n\nVercel support is kept as a reference proof of concept — we do not run a hosted deployment. See [docs/VERCEL_DEPLOYMENT.md](./docs/VERCEL_DEPLOYMENT.md) if you want to self-deploy.\n\nKey points:\n- Uses stateless request handling with encrypted, principal-bound Redis replay and a shared atomic Redis rate limiter\n- Requires Clerk or bearer auth\n- Leave `MCP_TLS_*` unset (Vercel terminates HTTPS)\n- Set `MCP_PUBLIC_BASE_URL` to your deployment URL so advertised MCP endpoints never depend on request headers\n- Vercel does not support WebSockets — Streamable HTTP/SSE only\n\n\n\n\nDocker\n\n```bash\ndocker build -t portkey-admin-mcp .\ndocker run \\\n -e PORTKEY_API_KEY=your_key \\\n -e MCP_TRANSPORT=http \\\n -e MCP_HOST=0.0.0.0 \\\n -e MCP_PORT=3000 \\\n -e MCP_AUTH_MODE=bearer \\\n -e MCP_AUTH_TOKEN=your_secret \\\n -p 3000:3000 \\\n portkey-admin-mcp\n```\n\n\n\n### Health Endpoints\n\n| Path | Purpose |\n|------|---------|\n| `GET /health` | Server liveness |\n| `GET /ready` | Readiness (includes optional Portkey connectivity check) |\n| `GET /auth/info` | Auth configuration metadata |\n\n\n\n
Development
\n\n```bash\nnpm run dev # stdio with hot reload\nnpm run dev:http # HTTP with hot reload\nnpm test # unit + contract tests\nnpm run test:coverage # unit + contract tests with the enforced 80% line floor\nnpm run test:e2e # MCP protocol tests\nnpm run test:http # HTTP endpoint smoke test\nnpm run smoke # credentialed read-only Portkey API smoke suite\nnpm run ci # full pipeline (lint + typecheck + coverage + build + e2e + verify)\n```\n\nThe live smoke suite reports expected credential-scope denials and the explicitly\ntracked hosted control-plane route gaps as skips. Unexpected HTTP responses,\nnetwork errors, and response-contract failures still fail the run.\n\nThe required CI and release gates measure every TypeScript source file and fail\nbelow 80% line coverage. The current full report is 98.19% lines, 91.92%\nbranches, and 98.58% functions.\n\n`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`.\n\nContributions use pull requests and the checks documented in\n[`CONTRIBUTING.md`](CONTRIBUTING.md). Project decisions and maintainer roles are\ndocumented in [`GOVERNANCE.md`](GOVERNANCE.md). Report vulnerabilities through\n[`SECURITY.md`](SECURITY.md), and see [`SECURITY-ASSURANCE.md`](SECURITY-ASSURANCE.md)\nfor the public threat model and assurance case.\n\n\n\n
Community
\n\nQuestions 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).\n\n---\n\n
\n\n### Built With\n\n[](https://www.typescriptlang.org/)\n[](https://github.com/modelcontextprotocol/typescript-sdk)\n[](https://zod.dev/)\n[](https://biomejs.dev/)\n[](https://nodejs.org/)\n[](https://claude.ai/)\n\n[](https://semver.org/)\n[](https://www.conventionalcommits.org/)\n[](https://keepachangelog.com/)\n\n**[MIT License](LICENSE)** · Inspired by [r-huijts/portkey-admin-mcp-server](https://github.com/r-huijts/portkey-admin-mcp-server)\n\n\n \n \n \n \n \n\n\nAlso listed on [LobeHub](https://lobehub.com/mcp/codeswhat-portkey-admin-mcp) and [Glama](https://glama.ai/mcp/servers/CodesWhat/portkey-admin-mcp):\n\n[](https://lobehub.com/mcp/codeswhat-portkey-admin-mcp)\n\n\n\nBack to top\n\n
![\"Portkey](\"./assets/portkey-balloon-spin-light.webp\")
\n\n![\"npm](\"https://img.shields.io/npm/v/portkey-admin-mcp.svg\")
\n ![\"Node.js\"](\"https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg\"){kind=icon}
\n ![\"License:](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
\n![\"CI\"](\"https://github.com/CodesWhat/portkey-admin-mcp/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"OpenSSF](\"https://img.shields.io/ossf-scorecard/github.com/CodesWhat/portkey-admin-mcp?label=openssf+scorecard&style=flat\")
![\"Maintainability\"](\"https://qlty.sh/gh/CodesWhat/projects/portkey-admin-mcp/maintainability.svg\")
\n ![\"Code](\"https://qlty.sh/gh/CodesWhat/projects/portkey-admin-mcp/coverage.svg\")
\n![\"npm](\"https://img.shields.io/npm/dm/portkey-admin-mcp.svg\")
\n ![\"Mentioned](\"https://awesome.re/mentioned-badge.svg\"){kind=icon}
\n ![\"MCP](\"https://img.shields.io/badge/MCP-Registry-blue\"){kind=icon}
![\"Sponsor\"](\"https://img.shields.io/badge/Sponsor-ea4aaa?logo=githubsponsors&logoColor=white\"){kind=icon}
![\"CodesWhat\"](\"assets/codeswhat-logo-dark.svg\"){kind=logo}
\n ![\"portkey-admin-mcp](\"https://glama.ai/mcp/servers/CodesWhat/portkey-admin-mcp/badges/card.svg\")
\n\nBack to top\n\n