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

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

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

✨ Features

🔧 Tools (116)

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

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

Session Modes (HTTP)

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

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.

🛠️ 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)