How do I use portkey-admin-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@portkey-admin-mcp list all users in my organization" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Portkey Admin MCP Server

MCP server for Portkey Admin API. 116 tools for prompts, configs, analytics & more.

📑 Contents

🚀 Quick Start

Installation Methods

Method	Type	Setup
`npx portkey-admin-mcp`	Zero-install	Runs directly via npx
	Self-hosted	`docker pull` or build from source

npx (Recommended)

PORTKEY_API_KEY=your_key npx -y portkey-admin-mcp

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

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

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

git clone https://github.com/s-b-e-n-s-o-n/portkey-admin-mcp.git
cd portkey-admin-mcp
npm install
npm run build

Then use this config:

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

✨ Features

🔧 Tools (116)

Tool	Description
`list_all_users`	List all users in organization
`get_user`	Get user details
`update_user`	Update user
`delete_user`	Remove user
`invite_user`	Invite a new user
`list_user_invites`	List pending invites
`get_user_invite`	Get invite details
`delete_user_invite`	Cancel invite
`resend_user_invite`	Resend invite email
`get_user_stats`	Get user statistics

Tool	Description
`list_workspaces`	List all workspaces
`get_workspace`	Get workspace details
`create_workspace`	Create workspace
`update_workspace`	Update workspace
`delete_workspace`	Delete workspace
`add_workspace_member`	Add member to workspace
`list_workspace_members`	List workspace members
`get_workspace_member`	Get member details
`update_workspace_member`	Update member role
`remove_workspace_member`	Remove member

Tool	Description
`list_configs`	List gateway configs
`get_config`	Get config details
`create_config`	Create config
`update_config`	Update config
`delete_config`	Delete config
`list_config_versions`	List config version history

Tool	Description
`list_api_keys`	List API keys
`create_api_key`	Create API key
`get_api_key`	Get API key details
`update_api_key`	Update API key
`delete_api_key`	Delete API key
`list_virtual_keys`	List virtual keys
`create_virtual_key`	Create virtual key
`get_virtual_key`	Get virtual key details
`update_virtual_key`	Update virtual key
`delete_virtual_key`	Delete virtual key

Tool	Description
`list_collections`	List prompt collections
`create_collection`	Create a collection
`get_collection`	Get collection details
`update_collection`	Update collection
`delete_collection`	Delete collection

Tool	Description
`list_prompts`	List prompts
`create_prompt`	Create a prompt template
`get_prompt`	Get prompt details
`update_prompt`	Update a prompt
`delete_prompt`	Delete prompt
`publish_prompt`	Publish prompt version
`list_prompt_versions`	List version history
`render_prompt`	Render prompt with variables
`run_prompt_completion`	Execute prompt completion
`migrate_prompt`	Create-or-update prompt
`promote_prompt`	Promote prompt between environments
`validate_completion_metadata`	Validate billing metadata

Tool	Description
`create_prompt_partial`	Create reusable partial
`list_prompt_partials`	List partials
`get_prompt_partial`	Get partial details
`update_prompt_partial`	Update partial
`delete_prompt_partial`	Delete partial
`list_partial_versions`	List partial versions
`publish_partial`	Publish partial version

Tool	Description
`create_prompt_label`	Create label
`list_prompt_labels`	List labels
`get_prompt_label`	Get label details
`update_prompt_label`	Update label
`delete_prompt_label`	Delete label

Tool	Description
`list_guardrails`	List guardrails
`create_guardrail`	Create guardrail
`get_guardrail`	Get guardrail details
`update_guardrail`	Update guardrail
`delete_guardrail`	Delete guardrail

Tool	Description
`list_usage_limits`	List usage limits
`create_usage_limit`	Create usage limit
`get_usage_limit`	Get limit details
`update_usage_limit`	Update limit
`delete_usage_limit`	Delete limit

Tool	Description
`list_rate_limits`	List rate limits
`create_rate_limit`	Create rate limit
`get_rate_limit`	Get rate limit details
`update_rate_limit`	Update rate limit
`delete_rate_limit`	Delete rate limit

Tool	Description
`list_audit_logs`	List audit log entries

Tool	Description
`get_cost_analytics`	Get cost analytics data
`get_request_analytics`	Request analytics
`get_token_analytics`	Token usage analytics
`get_latency_analytics`	Latency analytics
`get_error_analytics`	Error analytics
`get_error_rate_analytics`	Error rate analytics
`get_users_analytics`	Per-user analytics
`get_cache_hit_latency`	Cache hit latency
`get_cache_hit_rate`	Cache hit rate

Tool	Description
`insert_log`	Insert log entry
`create_log_export`	Create log export
`list_log_exports`	List exports
`get_log_export`	Get export details
`update_log_export`	Update export
`start_log_export`	Start export job
`cancel_log_export`	Cancel export
`download_log_export`	Download export

Tool	Description
`create_feedback`	Create feedback
`update_feedback`	Update feedback
`get_trace`	Get trace details

Tool	Description
`list_providers`	List providers
`create_provider`	Create provider
`get_provider`	Get provider details
`update_provider`	Update provider
`delete_provider`	Delete provider

Tool	Description
`list_integrations`	List integrations
`create_integration`	Create integration
`get_integration`	Get integration details
`update_integration`	Update integration
`delete_integration`	Delete integration
`list_integration_models`	List custom models
`update_integration_models`	Update custom models
`delete_integration_model`	Delete custom model
`list_integration_workspaces`	List workspace access
`update_integration_workspaces`	Update workspace access

🏗️ Architecture

sequenceDiagram
    participant Client as Client (Claude)
    participant Transport as MCP Transport<br/>(Stdio or HTTP)
    participant Server as MCP Server
    participant Facade as PortkeyService
    participant Domain as Domain Service<br/>(e.g., UsersService)
    participant API as Portkey API

    Client->>Transport: Tool invocation request
    Transport->>Server: Forward request
    Server->>Server: Parse tool name & params
    Server->>Facade: Call delegated method
    Facade->>Domain: Delegate to domain service
    Domain->>API: HTTP GET /users
    API-->>Domain: JSON response
    Domain-->>Facade: Return typed data
    Facade-->>Server: Return data
    Server-->>Transport: Tool result
    Transport-->>Client: Display result

🚢 Deployment

Transports

Transport	Entrypoint	Use Case
`stdio`	`node build/index.js`	Local CLI tools (Claude Code, Cursor)
`Streamable HTTP`	`node build/server.js`	Remote clients, web, production

MCP_TRANSPORT is retained for compatibility, but transport selection is done by choosing the correct entrypoint.

Session Modes (HTTP)

Mode	Env	Best For	Tradeoff
Stateful	`MCP_SESSION_MODE=stateful` (default)	Single-instance always-on services	Session transport state is in memory
Stateless	`MCP_SESSION_MODE=stateless`	Autoscaling/serverless (Render scale-out, Vercel, Cloud Run)	`DELETE /mcp` not used; no server-side session tracking

Recommended Hosted Defaults (Team Setup)

For shared/team hosting, use:

MCP_SESSION_MODE=stateless
MCP_EVENT_STORE=redis
MCP_REDIS_URL=... (or REDIS_URL=...)
MCP_AUTH_MODE=clerk (or bearer for internal-only setups)
ALLOWED_ORIGINS=https://your-app-domain
MCP_READY_CHECK_MODE=portkey

This keeps MCP request handling stateless while preserving stream resumability across instances.

Event Store Modes

Mode	Env	Default	Purpose
Off	`MCP_EVENT_STORE=off`	`stateful` mode	No resumability store
Memory	`MCP_EVENT_STORE=memory`	`stateless` mode	In-process resumability
Redis	`MCP_EVENT_STORE=redis` + `MCP_REDIS_URL` or `REDIS_URL`	none	Shared resumability across instances

MCP_EVENT_TTL_SECONDS controls retention (default 3600). When MCP_EVENT_STORE=redis, the server resolves Redis URL in this order: MCP_REDIS_URL first, then REDIS_URL.

HTTP Mode

PORTKEY_API_KEY=your_key \
MCP_HOST=0.0.0.0 \
MCP_PORT=3000 \
MCP_SESSION_MODE=stateful \
MCP_EVENT_STORE=off \
MCP_AUTH_MODE=bearer \
MCP_AUTH_TOKEN=replace_with_long_random_secret \
node build/server.js

Exposes a single /mcp endpoint with session management via Mcp-Session-Id header.

HTTPS Mode (Native TLS)

PORTKEY_API_KEY=your_key \
MCP_HOST=0.0.0.0 \
MCP_PORT=3443 \
MCP_TLS_KEY_PATH=/etc/ssl/private/server.key \
MCP_TLS_CERT_PATH=/etc/ssl/certs/server.crt \
MCP_AUTH_MODE=clerk \
CLERK_ISSUER=https://your-clerk-domain \
node build/server.js

If you host behind a platform/load balancer (Vercel, Cloud Run, Fly, Nginx, Cloudflare), leave MCP_TLS_* unset and let the platform terminate HTTPS.

Clerk Auth (HTTP)

PORTKEY_API_KEY=your_key \
MCP_HOST=0.0.0.0 \
MCP_PORT=3000 \
MCP_SESSION_MODE=stateless \
MCP_EVENT_STORE=redis \
MCP_REDIS_URL=redis://localhost:6379 \
MCP_AUTH_MODE=clerk \
CLERK_ISSUER=https://your-clerk-domain \
CLERK_AUDIENCE=your-audience \
node build/server.js

Vercel

This repo includes Vercel routing files:

api/index.ts - Vercel function entrypoint
vercel.json - rewrites /, /mcp, /health, /ready, /auth/info to that function

Full setup guide (including public-repo security checklist):

docs/VERCEL_DEPLOYMENT.md

Recommended Vercel environment variables:

PORTKEY_API_KEY=...
MCP_SESSION_MODE=stateless
MCP_EVENT_STORE=redis
MCP_REDIS_URL=redis://...
MCP_AUTH_MODE=clerk (or bearer)
CLERK_ISSUER=https://your-clerk-domain (required when MCP_AUTH_MODE=clerk)
CLERK_AUDIENCE=your-audience (required when MCP_AUTH_MODE=clerk)
ALLOWED_ORIGINS=https://your-app-domain
MCP_TRUST_PROXY=true
MCP_READY_CHECK_MODE=portkey

Notes:

Leave MCP_TLS_* unset on Vercel (Vercel terminates HTTPS).
Keep MCP on Streamable HTTP/SSE (Vercel does not support WebSockets).
vercel.json sets function maxDuration to 300; adjust based on your plan limits.
For public repos, never commit keys; keep all credentials in Vercel Environment Variables only.

Quick MCP HTTP Test

After starting the HTTP server, run:

npm run test:http

Optional overrides:

MCP_TEST_BASE_URL=https://your-host
MCP_TEST_MCP_URL=https://your-host/mcp
MCP_TEST_BEARER_TOKEN=... (or MCP_TEST_AUTH_HEADER='Authorization: Bearer ...')

The script verifies /health, /ready, runs initialize, then runs tools/list.

Docker

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

Health Endpoints

GET / - Web status/auth helper page
GET /auth/info - Auth metadata (auth mode, session mode, event store mode, Clerk config flags, MCP endpoint URL)
GET /health - Server status
GET /ready - Readiness state (includes session mode/event store mode, and optional Portkey connectivity when MCP_READY_CHECK_MODE=portkey)

⚠️ Limitations

Enterprise Features

The following require a Portkey Enterprise plan with Admin API keys:

Analytics (cost, request, token, latency, error, cache, feedback)
Log exports
Audit logs
User management (list users, invites)
Provider creation

Scope-Gated Endpoints (Verified 2026-02-25)

Most 403 responses include Portkey error code AB03 ("not enough permissions"). This indicates missing API key scopes, not broken endpoint paths.

Endpoint Group	Typical Failing Tools	Required Scope(s)
Users	`list_all_users`, `get_user`	`users.list`, `users.view`
User Invites	`list_user_invites`, `get_user_invite`	`users.invites.list`, `users.invites.view`
API Keys	`list_api_keys`, `get_api_key`	`apiKeys.list`, `apiKeys.view` (+ API key management feature)
Audit Logs	`list_audit_logs`	`auditLogs.list`
Analytics Graphs	`get_cost_analytics`, `get_request_analytics`, etc.	`analytics.view`
Analytics Groups	`get_user_grouped_data`	`analytics.groups.view`
Integration Access	`list_integration_models`, `list_integration_workspaces`	`integrations.models.list`, `integrations.workspaces.list`

🛠️ Development

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

Built With

TypeScript Node.js Zod

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

↑ Back to top

portkey-admin-mcp