Portkey Admin MCP Server

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

📑 Contents

• 🚀 Quick Start
• ✨ Features
• 🔧 Tools
• 🏗️ Architecture
• 🚢 Deployment
• ▲ Vercel Guide
• 🔐 Security Policy
• ⚠️ Limitations

🚀 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

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

↑ Back to top