portkey-admin-mcp

Servidor MCP completo para a API de administração do AI Gateway https://portkey.ai com 151 ferramentas em 18 domínios.

Documentação

Servidor MCP Portkey Admin

A Portkey Admin API como um servidor MCP — 181 ferramentas em prompts, configs, chaves, análises, governança, implantações e muito mais.

[!important] Importante Desenvolvimento ativo de compatibilidade. A Palo Alto Networks concluiu a aquisição da Portkey em 29/05/2026 e agora apresenta a Portkey como o núcleo do Prisma AIRS AI Gateway. A Portkey Admin API permanece ativa, e seu OpenAPI oficial e changelog de produto continuaram adicionando superfícies de plano de controle até setembro de 2026; portanto, este projeto retomou o trabalho de cobertura da API. Ele tem como alvo a API compatível com Portkey (x-portkey-api-key), não o Prisma AIRS/Strata Cloud Manager diretamente. O Prisma AIRS AI Gateway atualmente possui uma superfície de gerenciamento e autenticação diferente, portanto não é uma substituição direta do PORTKEY_BASE_URL. Consulte o breve guia de interoperabilidade Prisma AIRS para o modelo lado a lado suportado e os critérios de adaptador.

Conteúdo

Início Rápido

Você precisa de uma chave de API Portkey com os escopos apropriados. Obtenha uma no seu painel da Portkey em API Keys.

Claude Code

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

Cursor / Windsurf / VS Code

Adicione à sua configuração MCP (.cursor/mcp.json, .windsurf/mcp.json ou .vscode/mcp.json):

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

Executar diretamente

PORTKEY_API_KEY=your_key npx -y portkey-admin-mcp

Para expor apenas um subconjunto focado de ferramentas em clientes stdio, defina PORTKEY_TOOL_DOMAINS:

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

Escopar domínios também é a maior alavanca no custo de contexto, não apenas no acesso. tools/list é paginado, e o catálogo completo de 181 ferramentas tem aproximadamente 400 KB quando um cliente segue nextCursor por todas as páginas. Restringir aos domínios que um cliente realmente precisa reduz isso aproximadamente de forma proporcional.

Compilar a partir do código-fonte

git clone https://github.com/CodesWhat/portkey-admin-mcp.git
cd portkey-admin-mcp
npm install && npm run build

Em seguida, use esta configuração:

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

O Que Você Pode Fazer

Categoria	Ferramentas	Exemplos
Prompts	14	Criar, versionar, renderizar, executar, migrar, promover prompts
Partials de Prompt	7	Fragmentos de prompt reutilizáveis com versionamento
Rótulos de Prompt	5	Organizar versões de prompt (produção, staging, dev)
Configs	6	Roteamento de gateway, cache, tentativas, balanceamento de carga
Implantações	5	Registrar, inspecionar, atualizar e arquivar Gateways auto-hospedados
Chaves de API	6	Criar, rotacionar e gerenciar chaves de API com escopo
Referências de Segredos	5	Gerenciar referências de segredos externos AWS, Azure e HashiCorp
Chaves Virtuais	5	Gerenciar chaves de acesso de provedores
Coleções	5	Agrupar prompts por aplicativo ou projeto
Provedores	5	Gerenciar configurações de provedores de IA
Integrações	11	Integrações de provedores, preços de modelos, modelos, acesso ao workspace
Integrações MCP	10	Integrações de ferramentas MCP externas
Servidores MCP	12	Registro de servidores MCP, capacidades e conexões ativas
Guardrails	14	Políticas de LLM e ferramentas MCP, mapeamentos de servidor, padrões da organização, exclusões de workspace
Limites de Uso	7	Limites de custo e consumo de tokens
Limites de Taxa	5	Controles de frequência de requisições
Análises	22	Custo, latência, erros, tokens, cache, feedback, grupos de provedores
Registro	10	Recuperação de logs, ingestão, exportação e restrições de campos
Rastreamento	2	Criação e atualização de feedback em rastreamentos
Usuários e Workspaces	24	Gerenciamento de usuários, convites, membros do workspace, mapeamentos de grupos SCIM
Auditoria	1	Acesso ao log de auditoria

181 ferramentas no total em 20 domínios de ferramentas. Consulte ENDPOINTS.md para a lista completa com descrições.

A linguagem de produto mais recente da Portkey apresenta cada vez mais credenciais de provedores como Provedores, enquanto a Admin API atual ainda expõe tanto /virtual-keys quanto /providers. Este servidor mantém ambos os domínios: Chaves Virtuais gerenciam credenciais de acesso de provedores, e Provedores gerenciam configurações de provedores do workspace.

Escopos de Chave de API

A maioria das ferramentas funciona com uma chave de serviço com escopo de workspace que tem as permissões Selecionar Tudo habilitadas. Isso cobre prompts, configs, chaves virtuais/de API, provedores, guardrails, integrações do workspace, servidores MCP, limites de taxa/uso, logs, conclusões de prompt e gerenciamento de usuários do workspace.

Se uma ferramenta retornar um 403 com o erro Portkey AB03, significa escopos ausentes — não um endpoint quebrado.

Ferramentas restritas a Enterprise e outros requisitos de escopo

Ferramentas restritas a Enterprise (53)

As seguintes ferramentas exigem um escopo de nível de organização que só está disponível em planos Portkey Enterprise. Elas retornam 403 You do not have enough permissions to execute this request em planos de workspace. Suas descrições incluem um sufixo Enterprise-gated. Returns 403 on non-Enterprise Portkey plans. para que os clientes MCP saibam de antemão.

Área	Ferramentas	Escopo necessário
Análises (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` de nível de organização
Implantações (5)	`list_deployments`, `register_deployment`, `get_deployment`, `update_deployment`, `archive_deployment`	Administração de implantação Enterprise
Auditoria	`list_audit_logs`	`audit_logs.list`
Integrações de nível de organização	`get_integration`, `list_integration_models`, `list_integration_workspaces`	`organisation_integrations.read`
Usuários de nível de organização	`list_all_users`, `get_user`, `get_user_stats`, `list_user_invites`	`organisation_users.list` / `organisation_users.read`
Guardrails da organização (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` e `organisation_exclusions.list/update`
Exportações de logs (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`	Exportação de Logs Enterprise + `logs.export`
Grupos SCIM (4)	`list_scim_groups`, `list_scim_workspace_mappings`, `create_scim_workspace_mapping`, `delete_scim_workspace_mapping`	SCIM habilitado + acesso de administrador da organização

Outros requisitos de escopo

Recurso	Necessário
Conclusões de prompt (`run_prompt_completion`)	Escopo `completions.write` + metadados de cobrança (`app`, `env`)
Criação de chave de serviço de API de nível de organização via `create_api_key`	`organisation_service_api_keys.create` (Enterprise)

Servidor HTTP (Experimental)

Status: O transporte HTTP funciona localmente e é coberto pela suíte de testes de integração, mas é uma prova de conceito — não há versão hospedada deste servidor, e a implantação hospedada não é atualmente um objetivo. Use stdio (npx) como o transporte suportado.

O servidor suporta HTTP Streamable para acesso remoto:

A autenticação HTTP controla o acesso ao servidor, mas não se passa por locatários Portkey separados. Todos os principais autenticados usam o mesmo PORTKEY_API_KEY configurado e podem invocar qualquer ferramenta habilitada e escopo que essa credencial conceder. Execute instâncias ou implantações separadas com credenciais Portkey com escopo separado e listas de permissão PORTKEY_TOOL_DOMAINS para diferentes níveis de confiança.

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

Ou via npx (o pacote portkey-admin-mcp inclui o binário 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 somente local, deixe MCP_HOST no padrão 127.0.0.1. Defina MCP_HOST=0.0.0.0 somente quando você precisar intencionalmente aceitar conexões de fora da máquina local, como Docker ou um proxy reverso em outra interface.

Referência completa de variáveis de ambiente

Variável	Padrão	Descrição
`PORTKEY_API_KEY`	(obrigatório)	Sua chave de API Portkey
`PORTKEY_BASE_URL`	`https://api.portkey.ai/v1`	URL base da API Admin Portkey. URLs Prisma AIRS/SCM não são compatíveis; requisições autenticadas nunca seguem redirecionamentos automaticamente
`PORTKEY_ALLOW_PRIVATE_BASE_URL`	—	Defina como `true` para permitir um `PORTKEY_BASE_URL` literal de loopback/privado
`PORTKEY_ALLOW_INSECURE_HTTP`	—	Defina separadamente como `true` apenas quando um gateway auto-hospedado confiável não puder usar HTTPS
`PORTKEY_TOOL_DOMAINS`	—	Lista de permissões no lado do servidor dos 20 domínios: `users`, `workspaces`, `configs`, `deployments`, `keys`, `collections`, `prompts`, `analytics`, `guardrails`, `limits`, `audit`, `labels`, `partials`, `tracing`, `logging`, `providers`, `secret-references`, `integrations`, `mcp-integrations`, `mcp-servers`. HTTP `?tools=` pode restringi-la, mas não pode expandi-la
`MCP_HOST`	`127.0.0.1`	Endereço de bind
`MCP_PORT`	`3000`	Porta
`MCP_PUBLIC_BASE_URL`	—	URL base absoluta pública para divulgar a partir de `/auth/info` e da página de status; recomendada para implantações hospedadas
`MCP_AUTH_MODE`	`none`	`none`, `bearer` ou `clerk` (`none` é bloqueado para HTTP, a menos que seja explicitamente sobrescrito)
`MCP_AUTH_TOKEN`	—	Segredo para autenticação bearer
`CLERK_ISSUER` / `CLERK_AUDIENCE`	—	Emissor e público obrigatórios quando `MCP_AUTH_MODE=clerk`
`CLERK_ALLOWED_SUBJECTS`	—	Lista de permissões CSV opcional de assuntos para Clerk; pelo menos uma política de autorização Clerk é obrigatória
`CLERK_ALLOWED_ORGANIZATION_IDS` / `CLERK_ALLOWED_ROLES`	—	Restrições CSV opcionais de organização e função; toda restrição configurada deve corresponder
`CLERK_REQUIRED_PERMISSIONS`	—	Permissões CSV opcionais que devem estar todas presentes no JWT Clerk verificado
`MCP_ALLOW_UNAUTHENTICATED_HTTP`	—	Defina como `true` apenas para depuração HTTP local não autenticada intencional
`MCP_SESSION_MODE`	`stateful`	`stateful` ou `stateless`
`MCP_MAX_SESSIONS`	`100`	Máximo de sessões com estado simultâneas ou manipuladores de requisições sem estado ativos
`MCP_EVENT_STORE`	`off`	`off`, `memory` ou `redis`; replay sem estado `GET /mcp` exige `memory` ou `redis`
`MCP_EVENT_TTL_SECONDS`	`300`	Retenção de replay em segundos
`MCP_EVENT_STORE_MAX_EVENTS`	`10000`	Máximo de eventos retidos pelo armazenamento de replay em memória; os eventos mais antigos são removidos primeiro
`MCP_EVENT_STORE_MAX_BYTES`	`67108864`	Aproximadamente o máximo de bytes serializados retidos pelo armazenamento de replay em memória
`MCP_EVENT_STORE_COMMAND_TIMEOUT_MS`	`5000`	Tempo limite do comando Redis para o armazenamento de eventos, em milissegundos; `0` desativa o tempo limite (restaura o comportamento ilimitado anterior à v6)
`MCP_REDIS_URL`	—	URL Redis para armazenamento de eventos compartilhado; produção exige `rediss://` e credenciais com escopo ACL
`MCP_EVENT_ENCRYPTION_KEY`	—	Chave AES base64 de 32 bytes obrigatória para payloads de replay Redis; gere com `openssl rand -base64 32`
`MCP_REDIS_KEY_PREFIX`	`mcp:event-store`	Namespace Redis dedicado para dados de replay
`MCP_TLS_KEY_PATH`	—	Chave TLS para HTTPS nativo
`MCP_TLS_CERT_PATH`	—	Certificado TLS para HTTPS nativo
`ALLOWED_ORIGINS`	—	Lista de permissões CORS; também usada para validar o cabeçalho `Host` (proteção contra rebinding de DNS) quando `MCP_AUTH_MODE=none`
`MCP_TRUST_PROXY`	`loopback`	Política de trust-proxy do Express. Use uma contagem exata de saltos não negativa ou uma sub-rede de proxy confiável; `true` é rejeitado porque confia em cabeçalhos de encaminhamento de qualquer peer
`RATE_LIMIT_STORE`	`memory`	`redis` para implantações multi-instância/serverless; modo de memória em produção exige `RATE_LIMIT_SINGLE_PROCESS=true`
`RATE_LIMIT_REDIS_URL`	—	URL Redis compartilhada do limitador, com fallback para `MCP_REDIS_URL` / `REDIS_URL`; produção exige `rediss://`
`RATE_LIMIT_REDIS_KEY_PREFIX`	`mcp:rate-limit`	Namespace Redis para buckets de tokens atômicos de pré-autenticação por IP e principal-mais-IP
`RATE_LIMIT_MAX_BUCKETS`	`10000`	Máximo de buckets locais em modo de memória explícito antes que novos clientes compartilhem capacidade de estouro

Contêineres de produção devem escolher sua topologia de limite de taxa explicitamente: defina RATE_LIMIT_STORE=redis para implantações multi-instância, ou defina RATE_LIMIT_SINGLE_PROCESS=true apenas para um único processo de longa duração.

Implantação no Vercel

O suporte ao Vercel é mantido como uma prova de conceito de referência — não executamos uma implantação hospedada. Consulte docs/VERCEL_DEPLOYMENT.md se quiser fazer auto-implantação.

Pontos principais:

Usa manipulação de requisições sem estado com replay Redis criptografado e vinculado ao principal e um limitador de taxa Redis atômico compartilhado
Exige autenticação Clerk ou bearer
Deixe MCP_TLS_* não definido (o Vercel encerra HTTPS)
Defina MCP_PUBLIC_BASE_URL para a URL da sua implantação para que os endpoints MCP divulgados nunca dependam de cabeçalhos de requisição
O Vercel não suporta WebSockets — apenas 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 Saúde

Caminho	Finalidade
`GET /health`	Vivacidade do servidor
`GET /ready`	Prontidão (inclui verificação opcional de conectividade com Portkey)
`GET /auth/info`	Metadados de configuração de autenticação

Desenvolvimento

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)

A suíte de smoke tests ao vivo relata negações esperadas de escopo de credenciais e as lacunas de rotas do plano de controle hospedado explicitamente rastreadas como skips. Respostas HTTP inesperadas, erros de rede e falhas de contrato de resposta ainda falham na execução.

Os portões obrigatórios de CI e release medem cada arquivo-fonte TypeScript e falham abaixo de 80% de cobertura de linhas. O relatório completo atual é 98,19% de linhas, 91,92% de branches e 98,58% de funções.

npm run dev:http agora exige MCP_AUTH_MODE=bearer ou MCP_AUTH_MODE=clerk por padrão. Para testes locais deliberados não autenticados, defina MCP_ALLOW_UNAUTHENTICATED_HTTP=true.

Contribuições usam pull requests e as verificações documentadas em CONTRIBUTING.md. Decisões de projeto e funções de mantenedores estão documentadas em GOVERNANCE.md. Relate vulnerabilidades por meio de SECURITY.md e consulte SECURITY-ASSURANCE.md para o modelo de ameaças público e o caso de garantia.

Comunidade

Perguntas e relatórios de bugs pertencem a Issues; discussões mais amplas, ideias e ajuda no uso do servidor pertencem a Discussions.

Os registros mantidos de pacote, registry, marketplace e diretório estão listados em Distribution and directories. Trate o catálogo de ferramentas gerado neste repositório como autoritativo quando um índice de terceiros estiver desatualizado.

Construído Com

Licença MIT · Inspirado por r-huijts/portkey-admin-mcp-server

[

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

Listagens no marketplace em LobeHub e Glama:

Voltar ao topo