Portkey Admin API control-plane MCP server with Prisma AIRS interoperability guidance.
io.github.CodesWhat/portkey-admin-mcp โ Portkey Admin API MCP Server
The Portkey Admin API control-plane is exposed as a Model Context Protocol (MCP) server. It provides 181 tools spanning prompts, configurations, keys, analytics, governance, deployments, and related areas, with interoperability guidance for Prisma AIRS. The project is implemented in TypeScript.
๐ ๏ธ Key Features
Portkey Admin API delivered as an MCP server
181 tools across prompts, configs, keys, analytics, governance, deployments, and more
Prisma AIRS interoperability guidance
Topics include: admin-api, ai-gateway, llmops, observability, mcp-server, and prompts
๐ Use Cases
Managing Portkey control-plane tasks via MCP tooling
Integrating Portkey Admin API workflows with Prisma AIRS guidance
Using LLM operations and observability-related controls through MCP
โก Developer Benefits
Centralized MCP server tooling for administrative functions
Clear alignment with developer toolchains (TypeScript)
The Portkey Admin API as an MCP server โ 194 tools across prompts, configs, keys, analytics, governance, deployments, and more.
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 October 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. Palo Alto now publishes a Prisma AIRS management specification, but it uses different authentication, multiple management bases, and a smaller domain set, so it is not a PORTKEY_BASE_URL swap. See the short Prisma AIRS interoperability guide for the supported side-by-side model and adapter criteria.
You need a Portkey API key with appropriate scopes. Get one from your Portkey dashboard under API Keys.
Version 0.15.0 uses MCP SDK v2 and serves protocol revision 2026-07-28 and
older clients on the same endpoint. It retires HTTP sessions and replay;
obsolete settings warn and are ignored. See
compatibility and deprecations before upgrading from 0.14.x.
Claude Code
bash
claude mcp add -e PORTKEY_API_KEY=your_key portkey-admin -- npx -y portkey-admin-mcp
Cursor / Windsurf
Add to your MCP config (Cursor: .cursor/mcp.json or ~/.cursor/mcp.json; Windsurf: ~/.codeium/windsurf/mcp_config.json):
Scoping domains is also the biggest lever on context cost, not just access. tools/list
is paginated, and the complete 194-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.
Build from source
bash
git clone https://github.com/CodesWhat/portkey-admin-mcp.git
cd portkey-admin-mcp
npm install && npm run build
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
Collections
5
Group prompts by app or project
Providers
5
Manage AI provider configurations
Integrations
11
Provider integrations, model pricing, models, workspace access
MCP Integrations
10
External MCP tool integrations
MCP Servers
12
MCP server registry, capabilities, and live connections
Guardrails
14
LLM and MCP-tool policies, server mappings, organisation defaults, workspace exclusions
Access Policies
5
Allow/deny users, groups, and agents access to MCP tools and provider models
Egress Allowlist
5
Organisation trust for custom outbound hosts
Usage Limits
7
Cost and token consumption limits
Rate Limits
5
Request frequency controls
Analytics
25
Cost, latency, errors, tokens, cache, feedback, provider, MCP, A2A, and workspace groups; organisation scope and workspace exclusions
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
194 tools total across 22 tool domains. See 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.
API Key Scopes
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.
If a tool returns a 403 with Portkey error AB03, it means missing scopes โ not a broken endpoint.
Enterprise-gated tools and other scope requirements
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.
Org-level service API key creation via create_api_key
organisation_service_api_keys.create (Enterprise)
HTTP Server (Experimental)
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.
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.
Full environment variable reference
Variable
Default
Description
PORTKEY_API_KEY
(required)
Your Portkey API key
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 allowlist of the 22 domains: users, workspaces, configs, deployments, keys, collections, prompts, analytics, guardrails, limits, audit, labels, partials, tracing, logging, providers, secret-references, integrations, mcp-integrations, mcp-servers, access-policies, egress-allowlist. HTTP ?tools= may narrow it but cannot expand it
MCP_TOOL_DOMAINS
โ
Fallback for PORTKEY_TOOL_DOMAINS, used only when that is unset
MCP_TRANSPORT
stdio
stdio or http; the Docker image picks its entrypoint from this (set http for the HTTP server)
MCP_HOST
127.0.0.1
Bind address
MCP_PORT
3000
Port
PORT
โ
Port override; takes precedence over MCP_PORT when set
MCP_PUBLIC_BASE_URL
โ
Public absolute base URL to advertise from /auth/info and the status page; recommended for hosted deployments
MCP_AUTH_MODE
none
none, bearer, or clerk (none is blocked for HTTP unless explicitly overridden)
MCP_AUTH_TOKEN
โ
Secret for bearer auth
CLERK_ISSUER / CLERK_AUDIENCE
โ
Required issuer and audience when MCP_AUTH_MODE=clerk
CLERK_JWKS_URL
<CLERK_ISSUER>/.well-known/jwks.json
JWKS endpoint for Clerk JWT verification; must be HTTPS. Set it only when the JWKS isn't at the default path
CLERK_ALLOWED_SUBJECTS
โ
Optional CSV subject allowlist for Clerk; at least one Clerk authorization policy is required
Old session/replay settings produce a warning containing names only. 0.14.x behavior is unchanged; see compatibility.
MCP_TLS_KEY_PATH
โ
TLS key for native HTTPS
MCP_TLS_CERT_PATH
โ
TLS cert for native HTTPS
MCP_TLS_CA_PATH
โ
Optional CA bundle for native HTTPS; only used when the TLS key and cert are set
MCP_SHUTDOWN_TIMEOUT_MS
10000
How long graceful shutdown waits before the process is forced to exit, in milliseconds; must be positive
MCP_MAX_REQUEST_SIZE
1mb
Maximum HTTP request body size; tool arguments also have a fixed budget of 10,000 array elements and object members, counted across nested input
MCP_READY_CHECK_MODE
local
local or portkey; portkey makes /ready also check Portkey connectivity
LOG_LEVEL
info
debug, info, warn, or error
ALLOWED_ORIGINS
โ
CORS allow-list; also used to validate the Host header (DNS-rebinding protection) when MCP_AUTH_MODE=none
CORS_ORIGIN
โ
Legacy fallback for ALLOWED_ORIGINS, used only when that is unset
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_ENABLED
true
Set to false to turn the pre-authentication rate limiter off
RATE_LIMIT_SINGLE_PROCESS
โ
Set to true to acknowledge a single-process deployment when using in-memory limiting in production
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
RATE_LIMIT_MAX
60
Maximum tokens in each pre-authentication IP and principal-plus-IP bucket
RATE_LIMIT_WINDOW_MS
60000
Rate-limit window in milliseconds
RATE_LIMIT_REFILL
60
Tokens refilled each window
RATE_LIMIT_MAX_BUCKETS
10000
Maximum local buckets in explicit memory mode before new clients share overflow capacity
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.
Vercel deployment
Vercel support is kept as a reference proof of concept โ we do not run a hosted deployment. See docs/VERCEL_DEPLOYMENT.md if you want to self-deploy.
Key points:
Uses stateless request handling and a shared atomic Redis rate limiter (SDK v2); GET replay is retired
Requires Clerk or bearer auth
Leave MCP_TLS_* unset (Vercel terminates HTTPS)
Set MCP_PUBLIC_BASE_URL to your deployment URL so advertised MCP endpoints never depend on request headers
Vercel does not support WebSockets โ Streamable HTTP/SSE only
npm run dev # stdio with hot reload
npm run dev:http # HTTP with hot reload
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.
list_audit_logs is Enterprise-only, so the smoke suite skips its check unless
PORTKEY_ORGANISATION_ID is set. Set it to your organisation ID to exercise that route.
The required CI and release gates measure every TypeScript source file and fail
below 80% line coverage. The CI and Coverage workflow reports show the current
line, branch, and function coverage.
The CI workflow
also runs the standalone Qlty CLI and publishes quality-reports artifacts for
each analyzed commit, including lint/security results, duplication, complexity,
and metrics. The Qlty maintainability badge remains Cloud-generated; local
analysis does not update it. Coverage is reported through Codecov, not Qlty,
and the Coverage workflow uploads it on every PR and on pushes to main and codex/**.
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.
Contributions use pull requests and the checks documented in
CONTRIBUTING.md. Project decisions and maintainer roles are
documented in GOVERNANCE.md. Report vulnerabilities through
SECURITY.md, and see SECURITY-ASSURANCE.md
for the public threat model and assurance case.
Roadmap
Release 0.15.0 moves to MCP SDK v2 and the 2026-07-28 spec.
The roadmap separates completed work from upstream contract and
tenant-verification gates. The MCP v2 migration shipped in 0.15.0 and keeps older
clients on the same endpoint while retiring session and replay storage. See compatibility and deprecations.
Community
Questions and bug reports belong in Issues; broader discussion, ideas, and help using the server belong in Discussions.
The maintained package, registry, marketplace, and directory records are listed
in Distribution and directories. Treat the generated
tool catalog in this repository as authoritative when a third-party index lags.