portkey-admin-mcp

> [!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 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 for the supported side-by-side model and adapter criteria.

Contents

• Quick Start
• What You Can Do
• API Key Scopes
• HTTP Server (Experimental)
• Architecture
• Prisma AIRS interoperability
• Verify a release
• Development
• Community
• Contributing
• Governance
• Security assurance
• 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

Scoping domains is also the biggest lever on context cost, not just access. `tools/list`

is paginated, and the complete 178-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

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

178 tools total across 20 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 (53)

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.

Other scope requirements

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.

Full environment variable reference

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

Development

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.

The required CI and release gates measure every TypeScript source file and fail

below 80% line coverage. The current full report is 98.19% lines, 91.92%

branches, and 98.58% functions.

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

Community

Questions and bug reports belong in Issues; broader discussion, ideas, and help using the server belong in Discussions.