Portkey Admin

GitHub Actions

Portkey Admin API control-plane MCP server with Prisma AIRS interoperability guidance

Add to Cursor Add to VS Code Run on PlugMCP

1{2  "mcpServers": {3    "portkey-admin-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ]9    }10  }11}

.cursor/mcp.jsonMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add portkey-admin-mcp -- npx -y portkey-admin-mcp@0.15.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "portkey-admin-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.15.0
Last checked: 2026-10-28

Stars: —
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Portkey Admin?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Portkey Admin need an API key?

No required environment variable is listed on this record.

What transport does Portkey Admin use?

Portkey Admin runs locally over stdio.

When was Portkey Admin last checked?

Last checked 2026-10-28. Portkey Admin API control-plane MCP server with Prisma AIRS interoperability guidance

From the publisher

Documentation

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.

Resource	Link
Tool reference	ENDPOINTS.md
Compatibility and deprecations	COMPATIBILITY.md
Changelog	CHANGELOG.md
Roadmap	ROADMAP.md
Architecture	Architecture
Deployment	HTTP configuration, Vercel guide
Distribution	Directories and release records, verify a release
Prisma AIRS	Interoperability guide
Contributing and governance	CONTRIBUTING.md, GOVERNANCE.md, Code of Conduct
Security	Reporting policy, assurance case

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 / 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 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.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"
      }
    }
  }
}

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

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

Area	Tools	Required scope
Analytics (25)	`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_cache_summary`, `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`, `get_analytics_group_providers`, `get_analytics_group_mcp`, `get_analytics_group_a2a`, `get_analytics_group_workspaces`	org-level `analytics.view`
Deployments (5)	`list_deployments`, `register_deployment`, `get_deployment`, `update_deployment`, `archive_deployment`	Enterprise deployment administration
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`
Organisation guardrails (6)	`get_organisation_defaults`, `update_organisation_defaults`, `list_input_guardrail_workspace_exclusions`, `update_input_guardrail_workspace_exclusions`, `list_output_guardrail_workspace_exclusions`, `update_output_guardrail_workspace_exclusions`	`organisation_settings.read/update` and `organisation_exclusions.list/update`
Log exports (8)	`create_log_export`, `list_log_exports`, `get_log_export`, `start_log_export`, `cancel_log_export`, `download_log_export`, `update_log_export`, `get_log_export_field_restrictions`	Enterprise Logs Export + `logs.export`
SCIM groups (4)	`list_scim_groups`, `list_scim_workspace_mappings`, `create_scim_workspace_mapping`, `delete_scim_workspace_mapping`	SCIM enabled + organisation admin access

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)

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.

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
`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_MAX_SESSIONS`	`100`	Maximum concurrent HTTP MCP request handlers (retained name)
`MCP_REDIS_URL`	—	Fallback Redis URL for shared rate limiting, after `RATE_LIMIT_REDIS_URL` and before `REDIS_URL`; production requires `rediss://`
`MCP_SESSION_MODE`, `MCP_SESSION_TIMEOUT`, `MCP_EVENT_*`, `MCP_REDIS_KEY_PREFIX`	Ignored as of 0.15.0	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 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

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

This example runs one long-lived container with in-memory rate limiting. Use RATE_LIMIT_STORE=redis and a TLS Redis URL for multiple instances.

Health Endpoints

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

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 existing Qlty maintainability and coverage badges remain Cloud-generated; local analysis does not update those badges. Coverage uploads and Cloud analysis still consume Qlty analysis minutes.

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.

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.

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.

Marketplace listings on LobeHub and Glama:

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

Resource

Link

Tool reference

ENDPOINTS.md

Compatibility and deprecations

COMPATIBILITY.md

Changelog

CHANGELOG.md

Roadmap

ROADMAP.md

Architecture

Deployment

HTTP configuration, Vercel guide

Distribution

Directories and release records, verify a release

Prisma AIRS

Interoperability guide

Contributing and governance

CONTRIBUTING.md, GOVERNANCE.md, Code of Conduct

Security

Reporting policy, assurance case

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

Category

Tools

Examples

Prompts

Create, version, render, execute, migrate, promote prompts

Prompt Partials

Reusable prompt fragments with versioning

Prompt Labels

Organize prompt versions (production, staging, dev)

Configs

Gateway routing, caching, retry, loadbalancing

Deployments

API Keys

Create, rotate, and manage scoped API keys

Secret References

Manage AWS, Azure, and HashiCorp external-secret references

Virtual Keys

Manage provider access keys

Collections

Group prompts by app or project

Providers

Manage AI provider configurations

Integrations

Provider integrations, model pricing, models, workspace access

MCP Integrations

External MCP tool integrations

MCP Servers

MCP server registry, capabilities, and live connections

Guardrails

LLM and MCP-tool policies, server mappings, organisation defaults, workspace exclusions

Access Policies

Allow/deny users, groups, and agents access to MCP tools and provider models

Egress Allowlist

Organisation trust for custom outbound hosts

Usage Limits

Cost and token consumption limits

Rate Limits

Request frequency controls

Analytics

Cost, latency, errors, tokens, cache, feedback, provider, MCP, A2A, and workspace groups; organisation scope and workspace exclusions

Logging

Log retrieval, ingestion, export, and field restrictions

Tracing

Feedback creation and updates on traces

Users & Workspaces

User management, invites, workspace members, SCIM group mappings

Audit

Audit log access

Area

Tools

Required scope

Analytics (25)

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_cache_summary, 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, get_analytics_group_providers, get_analytics_group_mcp, get_analytics_group_a2a, get_analytics_group_workspaces

org-level analytics.view

Deployments (5)

list_deployments, register_deployment, get_deployment, update_deployment, archive_deployment

Enterprise deployment administration

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

Organisation guardrails (6)

get_organisation_defaults, update_organisation_defaults, list_input_guardrail_workspace_exclusions, update_input_guardrail_workspace_exclusions, list_output_guardrail_workspace_exclusions, update_output_guardrail_workspace_exclusions

organisation_settings.read/update and organisation_exclusions.list/update

Log exports (8)

create_log_export, list_log_exports, get_log_export, start_log_export, cancel_log_export, download_log_export, update_log_export, get_log_export_field_restrictions

Enterprise Logs Export + logs.export

SCIM groups (4)

list_scim_groups, list_scim_workspace_mappings, create_scim_workspace_mapping, delete_scim_workspace_mapping

SCIM enabled + organisation admin access

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)

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

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_MAX_SESSIONS

100

Maximum concurrent HTTP MCP request handlers (retained name)

MCP_REDIS_URL

—

Fallback Redis URL for shared rate limiting, after RATE_LIMIT_REDIS_URL and before REDIS_URL; production requires rediss://

MCP_SESSION_MODE, MCP_SESSION_TIMEOUT, MCP_EVENT_*, MCP_REDIS_KEY_PREFIX

Ignored as of 0.15.0

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

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

Path

Purpose

GET /health

Server liveness

GET /ready

Readiness (includes optional Portkey connectivity check)

GET /auth/info

Auth configuration metadata

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)