Conectar um cliente de IA (MCP)

Onde encontrar no admin: System › Settings › API & AI agents (/agent/keys), a aba Connect an AI mostra a URL do endpoint e um trecho pronto para copiar para cada cliente, preenchido com uma chave que você acabou de criar.

O que faz

O Model Context Protocol (MCP) permite que um cliente de IA chame ferramentas. Seu painel hospeda um servidor MCP de administração em https://cloud.example.com/mcp/admin. Conecte sua própria ferramenta de IA a ele e pergunte em linguagem natural: "o que falta configurar?", "adicione meu cluster Proxmox", "crie planos com margem de 40%". O cliente chama as ferramentas de administração abaixo; o painel verifica os escopos, pede sua confirmação antes de qualquer ação de risco e registra cada chamada.

Dois endpoints MCP

/mcp é o endpoint de clientes (chaves de API de clientes, vk_; consulte MCP server). /mcp/admin é o endpoint de administração descrito aqui (chaves de administrador ak_ ou OAuth). Os dois nunca se misturam: as ferramentas de administração não ficam visíveis em /mcp, e /mcp/admin aceita apenas chaves de administrador.

Requisitos

Item	Requisito
Endpoint	https://cloud.example.com/mcp/admin no domínio do seu próprio painel. Copie a URL exata na aba Connect an AI. A mesma página lista uma URL local (http://127.0.0.1:<port>/mcp/admin) para ferramentas executadas no próprio servidor.
Credenciais	Uma admin API key (ak_...) com os escopos desejados, ou login OAuth para conectores web (OAuth connectors).
Cliente	Qualquer cliente MCP que suporte o transporte Streamable HTTP e um cabeçalho customizado Authorization. Versões de protocolo 2025-11-25, 2025-06-18 e 2025-03-26.
Rede	Se você colocar seu próprio proxy reverso na frente do painel, ele deverá repassar /mcp/admin. Os conectores web (claude.ai, ChatGPT) se conectam a partir dos servidores do fornecedor, portanto a URL deve estar acessível pela internet.

Preparar a infraestrutura

Nada para instalar no servidor. Se você restringir a chave por IP, certifique-se de que o endereço de onde seu cliente se conecta está no intervalo. Teste a acessibilidade primeiro:

curl -i -X POST https://cloud.example.com/mcp/admin

Uma resposta 401 com um cabeçalho WWW-Authenticate: Bearer ... resource_metadata=... significa que o endpoint está ativo e requer credenciais.

Conectar no NexCMP

1. Crie uma chave: System › Settings › API & AI agents › API keys › New key. Para um primeiro teste, use apenas admin:read; adicione escopos de gravação quando precisar. Veja Admin API keys.
2. Abra a aba Connect an AI. Enquanto a caixa de diálogo "key created" estiver visível, cada trecho abaixo já contém sua chave real. Caso contrário, ele exibirá o espaço reservado ak_YOUR_KEY.
3. Copie o trecho para o seu cliente e execute-o ou cole-o conforme descrito a seguir.

Claude Code

claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \
  --header "Authorization: Bearer ak_XXXX"

Em seguida, inicie o claude e pergunte "list the tools from nexcmp" ou "what is left to set up?".

Verificado em 30/10/2026 com o Claude Code 2.1: claude mcp add --transport http … grava no servidor (adicione -s project para mantê-lo no .mcp.json do projeto — o Claude Code pede sua aprovação para servidores de projetos na primeira vez). Para scripts, claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*" é executado sem o prompt de aprovação e permite que o Claude use apenas as ferramentas do painel.

Claude Desktop

Requer Node.js 18 ou mais recente. Adicione isto a claude_desktop_config.json (ele usa a ponte mcp-remote) e reinicie o Claude Desktop:

{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}

Se o seu sistema corromper o espaço no argumento do cabeçalho, coloque o valor inteiro em uma variável de ambiente, exatamente como para o endpoint de cliente: "args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"] com "env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }.

claude.ai (conector customizado)

Nenhuma chave necessária: ele faz login com OAuth. No claude.ai, abra as configurações de conectores, adicione um conector customizado, cole https://cloud.example.com/mcp/admin, faça login com sua conta de administrador do NexCMP e escolha as permissões na tela de consentimento. Detalhes: OAuth connectors.

ChatGPT (modo de desenvolvedor)

Nenhuma chave necessária. No ChatGPT, ative o modo de desenvolvedor, adicione um conector MCP com a URL https://cloud.example.com/mcp/admin, escolha OAuth e faça login com sua conta de administrador do NexCMP. Detalhes: OAuth connectors.

Codex CLI

Adicionar a ~/.codex/config.toml:

[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"

Em seguida, exporte a chave no shell que inicia o Codex:

export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth

Não interativo codex exec

Em codex exec (scripts, CI), o Codex não pede confirmação antes de chamar ferramentas e pula ferramentas que alteram dados. Adicione default_tools_approval_mode = "approve" sob [mcp_servers.nexcmp] para permitir que ele as chame; o painel ainda retorna uma prévia e pede confirmação para ações de dinheiro, segurança e exclusão. Verificado com o Codex CLI 0.166 em 30/10/2026.

Gemini CLI

Adicionar a ~/.gemini/settings.json:

{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}

O Gemini CLI desativa servidores MCP em pastas nas quais não confia. Inicie-o em uma pasta confiável (ou confie na pasta quando solicitado) e verifique com gemini mcp list — ele exibe nexcmp … Connected. Você pode manter a chave fora do arquivo com "Authorization": "Bearer $NEXCMP_KEY". Verificado com o Gemini CLI 0.66 em 30/10/2026.

Cursor

Adicionar a ~/.cursor/mcp.json (ou .cursor/mcp.json em um projeto):

{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}

Mantenha a chave fora dos arquivos de configuração

Onde o cliente suporta, leia a chave de uma variável de ambiente em vez de gravá-la no arquivo: o Codex faz isso por padrão (bearer_token_env_var), e o Cursor aceita "Bearer ${env:NEXCMP_KEY}". Nunca faça commit de um arquivo que contenha uma chave.

OpenAI Agents SDK (Python)

from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)

Uma execução completa (verificada com openai-agents 0.24 em 30/10/2026 — uma ferramenta de leitura, seguida por uma alteração de saldo que retornou a prévia de confirmação e foi aplicada na segunda chamada com confirm_token):

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())

OpenAI Responses API

Passe o servidor como uma ferramenta do tipo mcp. Mantenha require_approval ativado em always para que seu programa pergunte antes de cada chamada:

{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}

Qualquer outra coisa (HTTP simples)

Um cliente sem MCP pode chamar as mesmas ferramentas via HTTP. GET /v1/admin/agent/tools as lista, POST /v1/admin/agent/tools/<name> executa uma com um corpo JSON de argumentos e GET /v1/admin/openapi.json retorna uma descrição OpenAPI 3.1 (cada ferramenta é uma operação). Todas exigem Authorization: Bearer ak_....

Verificar

1. Sem um cliente, liste as ferramentas:

   curl -s https://cloud.example.com/mcp/admin \
     -H "Authorization: Bearer ak_XXXX" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

   A resposta é um resultado JSON-RPC com as ferramentas que seus escopos permitem.

2. No seu cliente, pergunte "run system_health". Ele retorna alertas, a integridade da infraestrutura conectada, pagamentos, e-mail, IA e o estado da licença.

3. Abra API & AI agents › Activity: as chamadas são listadas com o nome do cliente e mcp.

4. No servidor, sudo nexcmp status imprime uma linha "MCP admin" que diz ready quando o endpoint responde (HTTP 401 sem uma chave é o estado saudável).

Ferramentas

O servidor oferece 58 ferramentas. Um cliente vê apenas as ferramentas permitidas pelos escopos da sua chave: ferramentas de leitura precisam de admin:read, ferramentas de gravação precisam de seu próprio escopo. Ferramentas de gravação também recebem um argumento opcional confirm_token (consulte Confirmation). Os argumentos são validados contra o esquema de cada ferramenta: argumentos desconhecidos ou digitados incorretamente são rejeitados com uma mensagem que os identifica.

Os preços estão em USD: preços de planos em dólares por hora (hourly_usd), saldos em centavos. Segredos podem ser definidos, mas nunca são retornados.

Visão geral e logs

Ferramenta	O que faz	Escopo	Altera dados	Pede confirmação
system_health	Alertas que exigem atenção, integridade da infraestrutura, pagamentos, e-mail, IA, licença e status de atualização.	admin:read	Não	Não
setup_checklist	O que está configurado e o que falta: licença, infraestrutura, zona, modelos de SO, planos, pagamentos, e-mail, identidade visual, termos legais, pedido de teste.	admin:read	Não	Não
license_status	Status da licença e se existe uma versão mais recente do NexCMP.	admin:read	Não	Não
audit_search	Pesquisar no log de auditoria do administrador e no log de chaves de API.	admin:read	Não	Não

Configurações, identidade visual, termos legais, módulos

Ferramenta	O que faz	Escopo	Altera dados	Pede confirmação
settings_get	Ler configurações gerais (keys filtra; um * no final corresponde a um prefixo).	admin:read	Não	Não
settings_update	Alterar configurações gerais a partir de um objeto values plano. Apenas chaves listadas por settings_get são aceitas.	settings:write	Sim	Quando uma chave afeta pagamentos, segurança de login, chaves globais do site ou preços
branding_get	Nome da marca, cor, moeda de exibição, nome do vendedor, URLs do logotipo e do favicon.	admin:read	Não	Não
branding_update	Definir nome da marca (até 60 caracteres), cor (#rrggbb), moeda de exibição (usd ou vnd) e nome do vendedor.	settings:write	Sim	Não
branding_logo_set	Faça o upload de um logotipo claro ou escuro ou de um favicon a partir de uma URL https ou base64 (PNG, JPEG, WEBP, ICO ou SVG, até 512 KB).	settings:write	Sim	Não
legal_get	Termos de serviço e política de privacidade (em inglês e vietnamita) e os padrões neutros.	admin:read	Não	Não
legal_update	Defina o texto dos termos e da privacidade (markdown simples, sem HTML, até 50 KB cada). Uma string vazia restaura o padrão.	settings:write	Sim	Não
modules_get	Quais módulos opcionais estão ativados e quais podem ser alternados.	admin:read	Não	Não
module_set	Ative ou desative um módulo opcional (key deve ser um de settable).	settings:write	Sim	Não

E-mail e alertas

Ferramenta	O que faz	Escopo	Altera dados	Pede confirmação
smtp_get	Configurações de e-mail de envio (senha mascarada) e status da fila.	admin:read	Não	Não
smtp_configure	Configure o servidor SMTP. A alteração de host, porta ou segurança exige a senha novamente.	settings:write (+ secrets:write para a senha)	Sim	Não
smtp_test	Envie um e-mail de teste real com as configurações salvas.	settings:write	Envia um e-mail	Não
telegram_get	Canais de notificação do administrador (IDs de chat; tokens de bot nunca são retornados).	admin:read	Não	Não
telegram_configure	Adicione ou atualize o canal de alerta do Telegram (token do bot e ID do chat) e ative ou desative os alertas de administrador.	settings:write (+ secrets:write para o token)	Sim	Não
telegram_test	Envie uma mensagem de teste para o canal do Telegram.	settings:write	Envia uma mensagem	Não

Pagamentos e moeda

Ferramenta	O que faz	Escopo	Altera dados	Pede confirmação
payments_get	Status de Stripe, PayPal, criptomoeda (USDT) e transferência bancária, além de canais ativados e taxas.	admin:read	Não	Não
payment_configure	Defina as credenciais de um gateway (stripe, paypal, crypto ou bank).	billing:write (+ secrets:write)	Sim	Sempre
payment_test	Verifique as credenciais salvas de um gateway com o provedor.	billing:write	Não	Não
currency_get	Moeda de exibição e a taxa de USD para VND (automática ou manual).	admin:read	Não	Não
currency_set	Defina a moeda de exibição e/ou uma taxa manual (0 significa automático, caso contrário, de 15000 a 50000).	billing:write	Sim	Quando você altera a taxa manual

Infraestrutura e zonas

Ferramenta	O que faz	Escopo	Altera dados	Pede confirmação
cloudstack_get	Endpoint, zona e IDs de rede do CloudStack salvos (chaves mascaradas).	admin:read	Não	Não
cloudstack_test	Teste um endpoint com uma chave de API e segredo sem salvar; lista as zonas.	infra:write (+ secrets:write, porque você passa as chaves)	Não	Não
cloudstack_connect	Salve a conexão com o CloudStack.	infra:write (+ secrets:write)	Sim	Sempre
proxmox_list	Clusters do Proxmox VE adicionados como origens, com status de saúde.	admin:read	Não	Não
proxmox_add	Adicione um cluster do Proxmox VE com um token de API (user@realm!tokenid) e seu segredo.	infra:write (+ secrets:write)	Sim	Não
proxmox_test	Conecte-se a um cluster por ID; o primeiro sucesso fixa seu certificado TLS.	infra:write	Sim	Não
proxmox_attach_zone	Venda um cluster Proxmox em uma zona existente, opcionalmente com um nó como região.	infra:write	Sim	Não
zones_list	Zonas (localizações) que os clientes podem escolher.	admin:read	Não	Não
zone_create	Crie uma zona.	infra:write	Sim	Não

Catálogo e planos

Ferramenta	O que faz	Escopo	Altera dados	Pede confirmação
templates_list	Modelos de SO que os clientes podem instalar.	admin:read	Não	Não
templates_sync	Importe modelos de SO do CloudStack.	catalog:write	Sim	Não
template_update	Ative ou oculte um modelo, renomeie-o, defina o usuário de login ou a ordem.	catalog:write	Sim	Não
offerings_list	Ofertas de serviço do CloudStack (CPU, memória, disco raiz) para criar planos.	admin:read	Não	Não
plans_list	Planos com preço por hora e por mês, tamanho, zona e quantos servidores os utilizam.	admin:read	Não	Não
plan_create	Crie um plano. Preço como hourly_usd. Os planos do CloudStack precisam de cs_offering_id; os planos do Proxmox precisam de backend_id.	catalog:write	Sim	Não
plan_update	Renomeie, exiba ou oculte, ative ou desative, ou reprecifique um plano. Alterações de tamanho em um plano em uso exigem uma cópia.	catalog:write	Sim	Quando o preço muda
plans_from_offerings	Gere uma tabela de planos iniciais a partir de ofertas (ou tamanhos do Proxmox) usando seu custo e uma porcentagem de margem. Retorna uma prévia; chame novamente com apply=true para criar os planos.	catalog:write	Com apply=true	Sempre na aplicação
quota_defaults_get	Limites padrão de clientes.	admin:read	Não	Não
quota_defaults_set	Alterar configurações de quota_*.	catalog:write	Sim	Não
coupons_list	Lotes de códigos de desconto e brinde.	admin:read	Não	Não
coupon_create	Criar um lote de códigos: tipo money (valor nominal em centavos de USD) ou percent (1 a 100, com desconto máximo).	catalog:write	Sim	Sempre

Clientes e revendedores

Ferramenta	O que faz	Escopo	Altera dados	Pede confirmação
customers_search	Localizar clientes por e-mail, nome ou IP.	admin:read	Não	Não
customer_get	A conta, o saldo, os servidores e o faturamento recente de um cliente.	admin:read	Não	Não
customer_adjust_balance	Adicionar (positivo) ou remover (negativo) crédito em centavos de USD. Um motivo é obrigatório.	billing:write	Sim	Sempre
customer_block	Bloquear um cliente, opcionalmente parando seus servidores. Um motivo é obrigatório.	customers:write	Sim	Sempre
customer_unblock	Desbloquear um cliente.	customers:write	Sim	Não
resellers_list	Revendedores com carteira e status.	admin:read	Não	Não
reseller_get	O site, a carteira, os usuários e os gateways de um revendedor.	admin:read	Não	Não

Provedor de IA

Ferramenta	O que faz	Escopo	Altera dados	Pede confirmação
ai_provider_get	O provedor compatível com OpenAI usado pelo AI Chat e pelo AI Agent do cliente (chave mascarada).	admin:read	Não	Não
ai_provider_set	Definir o provedor: URL base, modelo, chave de API, modelos de fallback, esforço de raciocínio, ativado.	ai:write (+ secrets:write para a chave)	Sim	Não
ai_provider_test	Fazer uma pergunta ao provedor salvo para verificar se funciona.	ai:write	Não	Não

Arquivos de configuração

Ferramenta	O que faz	Escopo	Altera dados	Pede confirmação
config_export	Exportar a configuração como YAML (segredos se tornam referências secret://).	admin:read	Não	Não
config_plan	Comparar uma configuração YAML com o painel ativo e listar o que mudaria.	admin:read	Não	Não
config_apply	Aplicar uma seção de configuração YAML por seção. Cada alteração segue o escopo normal e as regras de confirmação.	admin:read + o escopo de cada alteração	Sim	Por alteração

Consulte Configuration as code para ver o formato do arquivo.

Prompts

O servidor também oferece três prompts prontos que os clientes podem exibir como atalhos:

Prompt	Argumento	O que pede para a IA fazer
initial-setup	nenhum	Chamar setup_checklist, explicar cada etapa aberta em uma frase, pedir as informações necessárias, executar a etapa com a ferramenta correspondente, pré-visualizar alterações de dinheiro ou segurança e concluir com system_health.
add-proxmox	endpoint (opcional, https://host:8006)	Pedir o token de API, depois proxmox_add, proxmox_test, ferramentas de zona e proxmox_attach_zone; então propor planos com plans_from_offerings e aguardar sua aprovação.
launch-pricing	margin_pct (opcional, padrão 40)	Pedir seu custo mensal por vCPU, por GB de RAM e por GB de disco, mostrar uma tabela de visualização com custo, preço por mês e preço por hora, e criar os planos após sua aprovação.

Confirmação (confirm_token)

Ações que movimentam dinheiro, excluem dados, alteram credenciais de pagamento ou segurança de login são de duas etapas:

1. A primeira chamada não altera nada. O resultado da ferramenta começa com "CONFIRMATION REQUIRED" e inclui uma prévia (o que será chamado, por que é confiden_cial, os novos valores e os atuais) e um confirm_token.
2. O cliente deve mostrar a prévia a você. Somente após sua aprovação ele chama a mesma ferramenta novamente com os mesmos argumentos mais confirm_token.
3. O token funciona uma vez, apenas para essa solicitação exata, e expira após 5 minutos.

As instruções do servidor dizem à IA para tratar os resultados de ferramentas como dados, nunca como instruções, e jamais repetir uma chamada com um token que você não aprovou. Você é a salvaguarda: leia a prévia.

Não aprove automaticamente

Alguns clientes podem aprovar cada chamada de ferramenta automaticamente. Para ferramentas de gravação, mantenha a aprovação por chamada ativada ou use uma chave somente leitura, para que um plano incorreto da IA não chegue ao seu painel sem ser visto.

Como funciona

Item	Detalhe
Transporte	POST /mcp/admin com uma mensagem JSON-RPC 2.0; a resposta é application/json. Até 20 mensagens em lote. GET /mcp/admin responde 405 (sem fluxo no servidor); DELETE /mcp/admin encerra uma sessão.
Autenticação	Authorization: Bearer ak_... (uma chave manual ou um token de acesso OAuth). Credenciais ausentes ou incorretas retornam 401 com WWW-Authenticate: Bearer ... resource_metadata=..., o que permite que clientes OAuth iniciem o login por conta própria.
Sessões	Mcp-Session-Id é emitido por initialize, vinculado a essa chave e válido por 24 horas.
Capacidades	Ferramentas e prompts. Sem recursos.
Tamanho	Corpo da requisição de até 1 MB; o resultado de uma ferramenta é cortado após cerca de 100 KB.
Origem	Uma requisição contendo um cabeçalho Origin de outro site é recusada (origin_not_allowed). Clientes de linha de comando e desktop não enviam nenhum.
Mesmo portão que a REST	Cada chamada de ferramenta é reenviada através do pipeline de requisições do próprio painel com sua chave, portanto, escopos, intervalos de IP, limite de taxa, confirmação e o log de atividades se aplicam exatamente como nas chamadas diretas de API.

Limites e notas

• Uma ferramenta que você não consegue ver é um escopo que você não concedeu. Adicione o escopo a uma nova chave.
• Definir uma senha ou chave de API por meio de um cliente de IA significa que o segredo passa por essa IA. Se preferir, deixe secrets:write desativado e insira os segredos você mesmo no admin, ou use o campo Secret do AI Chat (AI Chat in the admin) ou referências secret:// (Configuration as code).
• Os clientes não compartilham sessões: cada conexão começa com initialize.
• Revogue a chave em API & AI agents para cortar o acesso de um cliente de IA imediatamente.

Resolução de problemas

Sintoma	Causa	Correção
401 invalid_key	Chave incorreta, truncada ou que não seja de admin (por exemplo, uma chave vk_)	Use uma chave ak_.
401 key_expired ou key_revoked	A chave esgotou ou foi revogada	Crie uma nova chave.
403 ip_not_allowed	Seu IP está fora dos intervalos de IP da chave	Conecte-se a partir de um IP permitido.
403 origin_not_allowed	Uma página de navegador em outra origem chamou o endpoint	Use um cliente de desktop ou CLI.
404 em uma requisição com Mcp-Session-Id	A sessão pertence a outra chave ou expirou	Envie initialize novamente.
400 unsupported MCP-Protocol-Version	O cliente usa uma versão que o servidor desconhece	Atualize o cliente; suportados: 2025-11-25, 2025-06-18, 2025-03-26.
A lista de ferramentas é curta	Escopos da chave	Crie uma chave com mais escopos.
insufficient_scope em uma chamada	Uma ferramenta precisa de um segundo escopo, por exemplo secrets:write	Adicione o escopo a uma nova chave.
429 rate_limited	Mais chamadas por minuto do que a chave permite	Aguarde por Retry-After ou aumente o limite em uma nova chave.
claude.ai ou ChatGPT não conseguem se conectar	A URL não é alcançável a partir da internet, ou um proxy bloqueia /mcp/admin ou /oauth-admin/	Verifique o DNS, o TLS e o proxy reverso.

Para todos os códigos de erro, consulte Admin API keys.