portkey-admin-mcp

Servidor MCP completo para la API de administración de AI Gateway de https://portkey.ai con 151 herramientas en 18 dominios.

GitHub

Documentación

Servidor MCP de Portkey Admin

La API de administración de Portkey como servidor MCP: 181 herramientas en prompts, configuraciones, claves, analíticas, gobernanza, despliegues y más.

[!important] Importante Desarrollo activo de compatibilidad. Palo Alto Networks completó su adquisición de Portkey el 2026‑05‑29 y ahora presenta Portkey como el núcleo de Prisma AIRS AI Gateway. La API de administración de Portkey sigue activa, y su OpenAPI oficial y el registro de cambios del producto continuaron añadiendo superficies de plano de control hasta septiembre de 2026; por lo tanto, este proyecto ha reanudado el trabajo de cobertura de la API. Está dirigido a la API compatible con Portkey (x-portkey-api-key), no directamente a Prisma AIRS/Strata Cloud Manager. Prisma AIRS AI Gateway actualmente tiene una superficie de gestión y autenticación diferente, por lo que no es un reemplazo directo de PORTKEY_BASE_URL. Consulta la breve guía de interoperabilidad con Prisma AIRS para conocer el modelo lado a lado compatible y los criterios de adaptadores.

Contenido

Inicio rápido

Necesitas una clave de API de Portkey con los ámbitos adecuados. Obtén una desde tu panel de Portkey en 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ñade 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

Para exponer solo un subconjunto enfocado de herramientas en clientes stdio, establece PORTKEY_TOOL_DOMAINS:

PORTKEY_API_KEY=your_key \
PORTKEY_TOOL_DOMAINS=prompts,analytics \
npx -y portkey-admin-mcp

Limitar los dominios también es la mayor palanca sobre el costo de contexto, no solo sobre el acceso. tools/list está paginado, y el catálogo completo de 181 herramientas es de aproximadamente 400 KB una vez que un cliente sigue nextCursor a través de cada página. Reducir a los dominios que un cliente realmente necesita recorta eso de manera aproximadamente proporcional.

Compilar desde el código fuente

git clone https://github.com/CodesWhat/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"
      }
    }
  }
}

Lo que puedes hacer

Categoría	Herramientas	Ejemplos
Prompts	14	Crear, versionar, renderizar, ejecutar, migrar, promocionar prompts
Fragmentos de prompts	7	Fragmentos de prompts reutilizables con versionado
Etiquetas de prompts	5	Organizar versiones de prompts (producción, staging, desarrollo)
Configuraciones	6	Enrutamiento de gateway, caché, reintentos, balanceo de carga
Despliegues	5	Registrar, inspeccionar, actualizar y archivar gateways autoalojados
Claves de API	6	Crear, rotar y gestionar claves de API con ámbito
Referencias de secretos	5	Gestionar referencias de secretos externos de AWS, Azure y HashiCorp
Claves virtuales	5	Gestionar claves de acceso de proveedores
Colecciones	5	Agrupar prompts por aplicación o proyecto
Proveedores	5	Gestionar configuraciones de proveedores de IA
Integraciones	11	Integraciones de proveedores, precios de modelos, modelos, acceso al espacio de trabajo
Integraciones MCP	10	Integraciones de herramientas MCP externas
Servidores MCP	12	Registro de servidores MCP, capacidades y conexiones en vivo
Guardarraíles	14	Políticas de LLM y herramientas MCP, mapeos de servidores, valores predeterminados de organización, exclusiones de espacios de trabajo
Límites de uso	7	Límites de costo y consumo de tokens
Límites de tasa	5	Controles de frecuencia de solicitudes
Analíticas	22	Costo, latencia, errores, tokens, caché, comentarios, grupos de proveedores
Registro	10	Recuperación de registros, ingesta, exportación y restricciones de campos
Trazado	2	Creación y actualización de comentarios en trazas
Usuarios y espacios de trabajo	24	Gestión de usuarios, invitaciones, miembros del espacio de trabajo, mapeos de grupos SCIM
Auditoría	1	Acceso al registro de auditoría

181 herramientas en total en 20 dominios de herramientas. Consulta ENDPOINTS.md para ver la lista completa con descripciones.

El lenguaje de producto más reciente de Portkey presenta cada vez más las credenciales de proveedores como Proveedores, mientras que la API de administración actual aún expone tanto /virtual-keys como /providers. Este servidor mantiene ambos dominios: las Claves virtuales gestionan las credenciales de acceso de proveedores, y los Proveedores gestionan las configuraciones de proveedores del espacio de trabajo.

Ámbitos de claves de API

La mayoría de las herramientas funcionan con una clave de servicio con ámbito de espacio de trabajo que tenga habilitados los permisos de Seleccionar todo. Eso cubre prompts, configuraciones, claves virtuales/de API, proveedores, guardarraíles, integraciones del espacio de trabajo, servidores MCP, límites de tasa/uso, registros, completaciones de prompts y gestión de usuarios del espacio de trabajo.

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

Herramientas restringidas a Enterprise y otros requisitos de ámbito

Herramientas restringidas a Enterprise (53)

Las siguientes herramientas requieren un ámbito a nivel de organización que solo está disponible en los planes Enterprise de Portkey. Devuelven 403 You do not have enough permissions to execute this request en planes de espacio de trabajo. Sus descripciones incluyen un sufijo Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. para que los clientes MCP lo sepan de antemano.

Área	Herramientas	Ámbito requerido
Analíticas (22)	`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`	`analytics.view` a nivel de organización
Despliegues (5)	`list_deployments`, `register_deployment`, `get_deployment`, `update_deployment`, `archive_deployment`	Administración de despliegues Enterprise
Auditoría	`list_audit_logs`	`audit_logs.list`
Integraciones a nivel de organización	`get_integration`, `list_integration_models`, `list_integration_workspaces`	`organisation_integrations.read`
Usuarios a nivel de organización	`list_all_users`, `get_user`, `get_user_stats`, `list_user_invites`	`organisation_users.list` / `organisation_users.read`
Guardarraíles de organización (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` y `organisation_exclusions.list/update`
Exportaciones de registros (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`	Exportación de registros Enterprise + `logs.export`
Grupos SCIM (4)	`list_scim_groups`, `list_scim_workspace_mappings`, `create_scim_workspace_mapping`, `delete_scim_workspace_mapping`	SCIM habilitado + acceso de administrador de organización

Otros requisitos de ámbito

Característica	Requerido
Completaciones de prompts (`run_prompt_completion`)	Ámbito `completions.write` + metadatos de facturación (`app`, `env`)
Creación de claves de servicio de API a nivel de organización mediante `create_api_key`	`organisation_service_api_keys.create` (Enterprise)

Servidor HTTP (Experimental)

Estado: El transporte HTTP funciona localmente y está cubierto por el conjunto de pruebas de integración, pero es una prueba de concepto: no hay versión alojada de este servidor, y el despliegue alojado no es actualmente un objetivo. Usa stdio (npx) como transporte compatible.

El servidor admite HTTP Streamable para acceso remoto:

La autenticación HTTP controla el acceso al servidor, pero no suplanta a inquilinos separados de Portkey. Todos los principales autenticados usan el mismo PORTKEY_API_KEY configurado y pueden invocar cualquier herramienta habilitada y ámbito que esa credencial otorgue. Ejecuta instancias o despliegues separados con credenciales de Portkey con ámbito separado y listas de permitidos PORTKEY_TOOL_DOMAINS para diferentes niveles de confianza.

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 HTTP solo local, deja MCP_HOST en su valor predeterminado 127.0.0.1. Establece MCP_HOST=0.0.0.0 solo cuando necesites intencionalmente aceptar conexiones desde fuera de la máquina local, como Docker o un proxy inverso en otra interfaz.

Referencia completa de variables de entorno

Variable	Valor por defecto	Descripción
`PORTKEY_API_KEY`	(obligatorio)	Tu clave de API de Portkey
`PORTKEY_BASE_URL`	`https://api.portkey.ai/v1`	URL base de la API de administración de Portkey. Las URLs de Prisma AIRS/SCM no son compatibles; las solicitudes con credenciales nunca siguen redirecciones automáticamente
`PORTKEY_ALLOW_PRIVATE_BASE_URL`	—	Establécelo en `true` para permitir un `PORTKEY_BASE_URL` literal de loopback/privado
`PORTKEY_ALLOW_INSECURE_HTTP`	—	Establécelo por separado en `true` solo cuando una puerta de enlace autohospedada de confianza no pueda usar HTTPS
`PORTKEY_TOOL_DOMAINS`	—	Lista de permitidos del lado del servidor de los 20 dominios: `users`, `workspaces`, `configs`, `deployments`, `keys`, `collections`, `prompts`, `analytics`, `guardrails`, `limits`, `audit`, `labels`, `partials`, `tracing`, `logging`, `providers`, `secret-references`, `integrations`, `mcp-integrations`, `mcp-servers`. El `?tools=` HTTP puede restringirla pero no ampliarla
`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; recomendada 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
`CLERK_ISSUER` / `CLERK_AUDIENCE`	—	Emisor y audiencia obligatorios cuando `MCP_AUTH_MODE=clerk`
`CLERK_ALLOWED_SUBJECTS`	—	Lista de permitidos CSV opcional de sujetos para Clerk; se requiere al menos una política de autorización de Clerk
`CLERK_ALLOWED_ORGANIZATION_IDS` / `CLERK_ALLOWED_ROLES`	—	Restricciones CSV opcionales de organización y rol; cada restricción configurada debe coincidir
`CLERK_REQUIRED_PERMISSIONS`	—	Permisos CSV opcionales que deben estar todos presentes en el JWT de Clerk verificado
`MCP_ALLOW_UNAUTHENTICATED_HTTP`	—	Establécelo en `true` solo para depuración HTTP local no autenticada intencional
`MCP_SESSION_MODE`	`stateful`	`stateful` o `stateless`
`MCP_MAX_SESSIONS`	`100`	Máximo de sesiones con estado concurrentes o manejadores de solicitudes sin estado activos
`MCP_EVENT_STORE`	`off`	`off`, `memory` o `redis`; la reproducción `GET /mcp` sin estado requiere `memory` o `redis`
`MCP_EVENT_TTL_SECONDS`	`300`	Retención de reproducción en segundos
`MCP_EVENT_STORE_MAX_EVENTS`	`10000`	Máximo de eventos retenidos por el almacén de reproducción en memoria; los eventos más antiguos se eliminan primero
`MCP_EVENT_STORE_MAX_BYTES`	`67108864`	Aproximadamente el máximo de bytes serializados retenidos por el almacén de reproducción en memoria
`MCP_EVENT_STORE_COMMAND_TIMEOUT_MS`	`5000`	Tiempo de espera del comando Redis para el almacén de eventos, en milisegundos; `0` desactiva el tiempo de espera (restaura el comportamiento ilimitado anterior a v6)
`MCP_REDIS_URL`	—	URL de Redis para el almacén de eventos compartido; la producción requiere `rediss://` y credenciales con ámbito ACL
`MCP_EVENT_ENCRYPTION_KEY`	—	Clave AES de 32 bytes en base64 obligatoria para los payloads de reproducción de Redis; genérala con `openssl rand -base64 32`
`MCP_REDIS_KEY_PREFIX`	`mcp:event-store`	Espacio de nombres Redis dedicado para datos de reproducción
`MCP_TLS_KEY_PATH`	—	Clave TLS para HTTPS nativo
`MCP_TLS_CERT_PATH`	—	Certificado TLS para HTTPS nativo
`ALLOWED_ORIGINS`	—	Lista de permitidos CORS; también se usa para validar el encabezado `Host` (protección contra rebinding de DNS) cuando `MCP_AUTH_MODE=none`
`MCP_TRUST_PROXY`	`loopback`	Política de trust-proxy de Express. Usa un número exacto no negativo de saltos o una subred de proxy de confianza; `true` se rechaza porque confía en los encabezados de reenvío de cada par
`RATE_LIMIT_STORE`	`memory`	`redis` para despliegues multi-instancia/serverless; el modo de memoria de producción requiere `RATE_LIMIT_SINGLE_PROCESS=true`
`RATE_LIMIT_REDIS_URL`	—	URL de Redis del limitador compartido, con respaldo a `MCP_REDIS_URL` / `REDIS_URL`; la producción requiere `rediss://`
`RATE_LIMIT_REDIS_KEY_PREFIX`	`mcp:rate-limit`	Espacio de nombres Redis para los buckets de tokens atómicos de pre-autenticación por IP y principal-más-IP
`RATE_LIMIT_MAX_BUCKETS`	`10000`	Máximo de buckets locales en modo de memoria explícito antes de que los nuevos clientes compartan capacidad de desbordamiento

Los contenedores de producción deben elegir explícitamente su topología de limitación de tasa: establece RATE_LIMIT_STORE=redis para despliegues multi-instancia, o establece RATE_LIMIT_SINGLE_PROCESS=true solo para un proceso único de larga duración.

Despliegue en Vercel

El soporte de Vercel se mantiene como una prueba de concepto de referencia — no ejecutamos un despliegue alojado. Consulta docs/VERCEL_DEPLOYMENT.md si deseas autodesplegarlo.

Puntos clave:

Usa manejo de solicitudes sin estado con reproducción Redis cifrada y vinculada al principal y un limitador de tasa Redis atómico compartido
Requiere autenticación Clerk o bearer
Deja MCP_TLS_* sin establecer (Vercel termina HTTPS)
Establece MCP_PUBLIC_BASE_URL a la URL de tu despliegue para que los endpoints MCP anunciados nunca dependan de los encabezados de solicitud
Vercel no admite WebSockets — solo Streamable HTTP/SSE Docker

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

Endpoints de salud

Ruta	Propósito
`GET /health`	Estado de vida del servidor
`GET /ready`	Estado de preparación (incluye verificació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: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)

La suite de pruebas de humo en vivo reporta las denegaciones esperadas por ámbito de credenciales y las brechas de rutas del plano de control alojado explícitamente rastreadas como omisiones. Las respuestas HTTP inesperadas, los errores de red y las fallas de contrato de respuesta aún hacen fallar la ejecución.

Las puertas de CI y lanzamiento requeridas miden cada archivo fuente de TypeScript y fallan por debajo del 80% de cobertura de líneas. El informe completo actual es 98.19% de líneas, 91.92% de ramas y 98.58% de funciones.

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

Las contribuciones usan solicitudes de extracción y las verificaciones documentadas en CONTRIBUTING.md. Las decisiones del proyecto y los roles de mantenedores están documentados en GOVERNANCE.md. Reporta vulnerabilidades a través de SECURITY.md y consulta SECURITY-ASSURANCE.md para el modelo de amenazas público y el caso de aseguramiento.

Comunidad

Las preguntas y reportes de errores pertenecen a Issues; la discusión más amplia, las ideas y la ayuda para usar el servidor pertenecen a Discussions.

Los registros mantenidos del paquete, registro, mercado y directorio se enumeran en Distribution and directories. Trata el catálogo de herramientas generado en este repositorio como autoritativo cuando un índice de terceros se retrase.

Construido con

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

[

](https://github.com/CodesWhat)

Listados de mercado en LobeHub y Glama:

Volver arriba