portkey-admin-mcp

Portkey Admin MCP Server

The full Portkey Admin API as an MCP server — 156 tools across prompts, configs, keys, analytics, and more.

---

Important

Maintenance mode. Portkey was acquired by Palo Alto Networks (completed 2026‑05‑29) and is being folded into the Prisma AIRS platform. The Portkey Admin API this server targets is live and unchanged as of June 2026, and this project still works end‑to‑end — but it is now in maintenance mode: security and dependency patches only, no new features, pending Palo Alto's post‑acquisition API roadmap. If the hosted Admin API is ever deprecated, point PORTKEY_BASE_URL at a self‑hosted Portkey gateway. See docs/audit-2026-06.md for the full assessment and security_best_practices_report.md for the 0.6.0 security-hardening review.

📑 Contents

• 🚀 Quick Start
• 🧰 What You Can Do
• 🔑 API Key Scopes
• 🌐 HTTP Server (Experimental)
• 🛠️ Development
• 🧾 Full tool list — ENDPOINTS.md

---

🚀 Quick Start

You need a Portkey API key with appropriate scopes. Get one from your Portkey dashboard under API Keys.

Claude Code

claude mcp add -e PORTKEY_API_KEY=your_key portkey-admin -- npx -y portkey-admin-mcp

Cursor / Windsurf / VS Code

Add to your MCP config (.cursor/mcp.json, .windsurf/mcp.json, or .vscode/mcp.json):

{ "mcpServers": { "portkey-admin": { "command": "npx", "args": ["-y", "portkey-admin-mcp"], "env": { "PORTKEY_API_KEY": "your_api_key" } } } }

Run directly

PORTKEY_API_KEY=your_key npx -y portkey-admin-mcp

To expose only a focused subset of tools in stdio clients, set PORTKEY_TOOL_DOMAINS:

PORTKEY_API_KEY=your_key
PORTKEY_TOOL_DOMAINS=prompts,analytics
npx -y portkey-admin-mcp

Build from source

git clone https://github.com/CodesWhat/portkey-admin-mcp.git cd portkey-admin-mcp npm install && npm run build

Then use this config:

{ "mcpServers": { "portkey-admin": { "command": "node", "args": ["/path/to/portkey-admin-mcp/build/index.js"], "env": { "PORTKEY_API_KEY": "your_api_key" } } } }

---

🧰 What You Can Do

Category	Tools	Examples
Prompts	14	Create, version, render, execute, migrate, promote prompts
Prompt Partials	7	Reusable prompt fragments with versioning
Prompt Labels	5	Organize prompt versions (production, staging, dev)
Configs	6	Gateway routing, caching, retry, loadbalancing
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	10	Provider integrations, models, workspace access
MCP Integrations	10	External MCP tool integrations
MCP Servers	10	MCP server registry and capabilities
Guardrails	5	Content safety policies
Usage Limits	7	Cost and token consumption limits
Rate Limits	5	Request frequency controls
Analytics	20	Cost, latency, errors, tokens, cache, feedback
Logging	8	Log ingestion and export
Tracing	2	Feedback creation and updates on traces
Users & Workspaces	20	User management, invites, workspace members
Audit	1	Audit log access

156 tools total. See ENDPOINTS.md for the full list with descriptions.

---

🔑 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.

Enterprise-gated tools (28)

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
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

Other scope requirements

Feature	Required
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.

---

🌐 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:

PORTKEY_API_KEY=your_key
MCP_HOST=127.0.0.1
MCP_PORT=3000
MCP_PUBLIC_BASE_URL=https://mcp.example.com
MCP_AUTH_MODE=bearer
MCP_AUTH_TOKEN=your_secret
node build/server.js

Or via npx (the portkey-admin-mcp package includes the HTTP binary):

PORTKEY_API_KEY=your_key MCP_AUTH_MODE=bearer MCP_AUTH_TOKEN=your_secret
npx -y -p portkey-admin-mcp portkey-admin-mcp-http

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

Variable	Default	Description
PORTKEY_API_KEY	(required)	Your Portkey API key
PORTKEY_BASE_URL	https://api.portkey.ai/v1	Portkey Admin API base URL. 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
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
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_ALLOWED_SUBJECTS	—	Optional CSV subject allowlist for Clerk; at least one Clerk authorization policy is required
CLERK_ALLOWED_ORGANIZATION_IDS / CLERK_ALLOWED_ROLES	—	Optional CSV organization and role constraints; every configured constraint must match
CLERK_REQUIRED_PERMISSIONS	—	Optional CSV permissions that must all be present in the verified Clerk JWT
MCP_ALLOW_UNAUTHENTICATED_HTTP	—	Set to true only for intentional local unauthenticated HTTP debugging
MCP_SESSION_MODE	stateful	stateful or stateless
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_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
MCP_REDIS_KEY_PREFIX	mcp:event-store	Dedicated Redis namespace for replay data
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)
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
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: setRATE_LIMIT_STORE=redis for multi-instance deployments, or setRATE_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 with encrypted, principal-bound Redis replay and a shared atomic Redis rate limiter
• 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 Docker

docker build -t portkey-admin-mcp . docker run
-e PORTKEY_API_KEY=your_key
-e MCP_TRANSPORT=http
-e MCP_HOST=0.0.0.0
-e MCP_PORT=3000
-e MCP_AUTH_MODE=bearer
-e MCP_AUTH_TOKEN=your_secret
-p 3000:3000
portkey-admin-mcp

Health Endpoints

Path	Purpose
GET /health	Server liveness
GET /ready	Readiness (includes optional Portkey connectivity check)
GET /auth/info	Auth configuration metadata

---

🛠️ Development

npm run dev # stdio with hot reload npm run dev:http # HTTP with hot reload npm test # unit + contract tests npm run test:e2e # MCP protocol tests npm run test:http # HTTP endpoint smoke test npm run ci # full pipeline (lint + typecheck + test + build + e2e + verify)

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.

---

Built With

MIT License · Inspired by r-huijts/portkey-admin-mcp-server