portkey-admin-mcp

<div align="center">

<img src="./assets/portkey-balloon-spin-light.webp" alt="Portkey Admin MCP icon" width="180" height="180">

<h1>Portkey Admin MCP Server</h1>

The full Portkey Admin API as an MCP server — 156 tools across prompts, configs, keys, analytics, 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> <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://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> </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> </p>

<hr>

[!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.

<h2 align="center">📑 Contents</h2>

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

<hr>

<h2 align="center" id="quick-start">🚀 Quick Start</h2>

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

<details> <summary><strong>Build from source</strong></summary>

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

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

</details>

<hr>

<h2 align="center" id="what-you-can-do">🧰 What You Can Do</h2>

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

<hr>

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

<hr>

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

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): ``bash 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: set RATE_LIMIT_STORE=redis for multi-instance deployments, or set RATE_LIMIT_SINGLE_PROCESS=true only for a single long-lived process.

<details> <summary><strong>Vercel deployment</strong></summary>

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

</details>

<details> <summary><strong>Docker</strong></summary>

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

</details>

Health Endpoints

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

<hr>

<h2 align="center" id="development">🛠️ Development</h2>

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.

---

<div align="center">

Built With

     

  

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

<a href="https://github.com/CodesWhat"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/codeswhat-logo-dark.svg" /> <source media="(prefers-color-scheme: light)" srcset="assets/codeswhat-logo-original.svg" /> <img src="assets/codeswhat-logo-original.svg" alt="CodesWhat" height="28"> </picture> </a>


<a href="#portkey-admin-mcp-server">Back to top</a>

</div>