Portkey Admin Mcp

[npm version] [Node.js] [License: MIT]

[CI] [OpenSSF Scorecard] [OpenSSF Best Practices] [Maintainability] [Code Coverage]

[npm downloads] [Mentioned in Awesome MCP Servers] [MCP Registry] [Sponsor]

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

Contents

• Documentation
• Quick Start
• What You Can Do
• API Key Scopes
• HTTP Server (Experimental)
• Architecture
• Distribution and directories
• Prisma AIRS interoperability
• Verify a release
• Development
• Roadmap
• Community
• Star History
• Built With
• Contributing
• Governance
• Security assurance
• Full tool list — ENDPOINTS.md

Documentation

Quick Start

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

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

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

VS Code

VS Code's .vscode/mcp.json uses a top-level servers key and needs a type:

{  "servers": {    "portkey-admin": {      "type": "stdio",      "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

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.

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

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

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.

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.

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.

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 \  -e RATE_LIMIT_SINGLE_PROCESS=true \  -p 3000:3000 \  portkey-admin-mcp

Health Endpoints

Development

npm run dev           # stdio with hot reloadnpm run dev:http      # HTTP with hot reloadnpm test              # unit + contract testsnpm run test:coverage # unit + contract tests with the enforced 80% line floornpm run test:e2e      # MCP protocol testsnpm run test:http     # HTTP endpoint smoke testnpm run smoke         # credentialed read-only Portkey API smoke suitenpm 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.

Star History