Servidor MCP de administración de Portkey

Servidor MCP para la API de administración de Portkey. Gestiona prompts, configuraciones, analíticas, claves API y más desde cualquier cliente MCP.

Inicio rápido

Necesitas una clave API de Portkey con los alcances (scopes) adecuados. Consigue una en tu panel de control de Portkey en la sección de API Keys.

Claude Code

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

Cursor / Windsurf / VS Code

Añádelo a tu configuración de MCP (.cursor/mcp.json, .windsurf/mcp.json o .vscode/mcp.json):

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

Ejecutar directamente

PORTKEY_API_KEY=your_key npx -y portkey-admin-mcp

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

Luego usa esta configuración:

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

Qué puedes hacer

Categoría	Herramientas	Ejemplos
Prompts	14	Crear, versionar, renderizar, ejecutar, migrar, promover prompts
Prompt Partials	7	Fragmentos de prompt reutilizables con control de versiones
Prompt Labels	5	Organizar versiones de prompts (producción, staging, desarrollo)
Configs	6	Enrutamiento de gateway, caché, reintentos, balanceo de carga
API Keys	5	Crear y gestionar claves API con alcances específicos
Virtual Keys	5	Gestionar claves de acceso de proveedores
Collections	5	Agrupar prompts por aplicación o proyecto
Providers	5	Gestionar configuraciones de proveedores de IA
Integrations	10	Integraciones de proveedores, modelos, acceso al espacio de trabajo
MCP Integrations	10	Integraciones de herramientas MCP externas
MCP Servers	10	Registro y capacidades del servidor MCP
Guardrails	5	Políticas de seguridad de contenido
Usage Limits	7	Límites de costes y consumo de tokens
Rate Limits	5	Controles de frecuencia de solicitudes
Analytics	20	Coste, latencia, errores, tokens, caché, feedback
Logging	8	Ingesta y exportación de registros
Tracing	3	Recuperación de feedback y trazas
Users & Workspaces	20	Gestión de usuarios, invitaciones, miembros del espacio de trabajo
Audit	1	Acceso al registro de auditoría

151 herramientas en total. Consulta ENDPOINTS.md para ver la lista completa con descripciones.

Alcances (Scopes) de la clave API

Las diferentes herramientas requieren diferentes alcances de clave API. Una clave de servicio con alcance de espacio de trabajo y permisos amplios funciona para la mayoría de las operaciones. Algunas funciones necesitan acceso adicional:

Función	Requerido
Analíticas, exportación de registros, registros de auditoría	Plan Enterprise + alcance `analytics.view`
Gestión de usuarios, invitaciones	Clave API a nivel de organización
Modelos/espacios de trabajo de integración	Clave API a nivel de organización
Completado de prompts	Alcance `completions.write` + metadatos de facturación

Si una herramienta devuelve un 403 con el error de Portkey AB03, significa que faltan alcances, no que el endpoint esté roto.

Servidor HTTP (Experimental)

Estado: El transporte HTTP funciona, pero el despliegue alojado no está totalmente validado para producción. Usa stdio (npx) para un funcionamiento fiable.

El servidor admite HTTP transmitible (Streamable HTTP) para acceso remoto:

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

O mediante npx (el paquete portkey-admin-mcp incluye el binario HTTP):

PORTKEY_API_KEY=your_key MCP_AUTH_MODE=bearer MCP_AUTH_TOKEN=your_secret \
  npx -y -p portkey-admin-mcp portkey-admin-mcp-http

Para uso exclusivo de HTTP local, deja MCP_HOST en su valor predeterminado 127.0.0.1. Establece MCP_HOST=0.0.0.0 solo cuando necesites intencionadamente aceptar conexiones desde fuera de la máquina local, como en Docker o un proxy inverso en otra interfaz.

Configuración

Variable	Predeterminado	Descripción
`PORTKEY_API_KEY`	(requerido)	Tu clave API de Portkey
`MCP_HOST`	`127.0.0.1`	Dirección de enlace
`MCP_PORT`	`3000`	Puerto
`MCP_PUBLIC_BASE_URL`	—	URL base absoluta pública para anunciar desde `/auth/info` y la página de estado; recomendado para despliegues alojados
`MCP_AUTH_MODE`	`none`	`none`, `bearer` o `clerk` (`none` está bloqueado para HTTP a menos que se anule explícitamente)
`MCP_AUTH_TOKEN`	—	Secreto para autenticación bearer
`MCP_ALLOW_UNAUTHENTICATED_HTTP`	—	Establecer en `true` solo para depuración HTTP local no autenticada intencionada
`MCP_SESSION_MODE`	`stateful`	`stateful` o `stateless`
`MCP_MAX_SESSIONS`	`100`	Máximo de sesiones MCP con estado concurrentes antes de que se rechacen nuevas solicitudes de inicialización
`MCP_EVENT_STORE`	`off`	`off`, `memory` o `redis`
`MCP_REDIS_URL`	—	URL de Redis para el almacén de eventos compartido
`MCP_TLS_KEY_PATH`	—	Clave TLS para HTTPS nativo
`MCP_TLS_CERT_PATH`	—	Certificado TLS para HTTPS nativo
`ALLOWED_ORIGINS`	—	Lista de permitidos de CORS
`MCP_TRUST_PROXY`	`false`	Confiar en encabezados de proxy (para proxies inversos)
`RATE_LIMIT_MAX_BUCKETS`	`10000`	Máximo de cubos de límite de tasa en memoria distintos antes de que los nuevos clientes compartan un cubo de desbordamiento

Se incluye soporte experimental para Vercel. Consulta docs/VERCEL_DEPLOYMENT.md para obtener instrucciones de configuración.

Puntos clave:

Utiliza modo sin estado con almacén de eventos Redis
Requiere autenticación Clerk o bearer
Deja MCP_TLS_* sin configurar (Vercel termina HTTPS)
Establece MCP_PUBLIC_BASE_URL en la URL de tu despliegue para que los endpoints MCP anunciados nunca dependan de los encabezados de solicitud
Vercel no admite WebSockets: solo HTTP/SSE transmitible

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=your_secret \
  -p 3000:3000 \
  portkey-admin-mcp

Endpoints de salud

Ruta	Propósito
`GET /health`	Actividad del servidor
`GET /ready`	Disponibilidad (incluye comprobación opcional de conectividad con Portkey)
`GET /auth/info`	Metadatos de configuración de autenticación

Desarrollo

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

npm run dev:http ahora requiere MCP_AUTH_MODE=bearer o MCP_AUTH_MODE=clerk por defecto. Para pruebas deliberadas no autenticadas solo locales, establece MCP_ALLOW_UNAUTHENTICATED_HTTP=true.

Licencia MIT · Inspirado en r-huijts/portkey-admin-mcp-server

↑ Volver arriba

portkey-admin-mcp