Servidor MCP

Onde no portal: API reference › Tools (https://<your-domain>/apidoc) mostra o endpoint e trechos para clientes; as chaves são criadas em API keys (/api-keys). Não há configuração no admin: o endpoint faz parte do painel.

O que faz

O Model Context Protocol (MCP) permite que um assistente de IA chame ferramentas. O NexCMP disponibiliza um endpoint MCP em https://<your-domain>/mcp. Cada operação da API pública se torna uma ferramenta (vm_list, vm_start, billing_wallet, ...), permitindo que um cliente pergunte ao assistente "quais das minhas VMs estão rodando?" ou "desligue a VM de staging". O assistente atua exclusivamente com a chave de API e as permissões do próprio cliente.

Configurando o próprio NexCMP com IA?

Esta página é o endpoint MCP do cliente (/mcp). Para permitir que um assistente de IA configure seu próprio painel como administrador, consulte Configure with AI (endpoint /mcp/admin, chaves de admin ak_).

Requisitos

Item	Requisito
Servidor	Nada para instalar: o endpoint é servido pelo painel e acessível onde quer que o painel esteja. O seu proxy reverso deve encaminhar `/mcp` para o painel.
Cliente	Uma API key (`vk_...`) com os escopos que o assistente precisa.
Cliente	Um cliente MCP que suporte o transporte Streamable HTTP e um cabeçalho customizado `Authorization`: Claude Code, Claude Desktop (através da ponte `mcp-remote`), Cursor, VS Code com o modo de agente do Copilot e similares.
Versões de protocolo	2025-11-25, 2025-06-18 e 2025-03-26.

Preparar a infraestrutura

Nada, além de garantir que https://<your-domain>/mcp não seja bloqueado por um firewall ou regra de proxy. Um cliente MCP baseado em navegador de outra origem é recusado a menos que essa origem seja permitida; clientes de linha de comando e de desktop não enviam cabeçalho Origin e funcionam normalmente.

Conectar (lado do cliente)

Crie uma API key no portal (API keys › Create key) apenas com os escopos que você deseja que o assistente use, com uma curta validade e, se possível, restrição de IP.

Adicione o servidor ao seu cliente. Substitua cloud.example.com e a chave.

Claude Code

bash

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

Cursor (~/.cursor/mcp.json ou .cursor/mcp.json; defina CLOUD_API_KEY no ambiente a partir do qual o Cursor é iniciado):

json

{
  "mcpServers": {
    "cloud": {
      "url": "https://cloud.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
    }
  }
}

Claude Desktop (requer Node.js 18+; claude_desktop_config.json), através da ponte mcp-remote:

json

{
  "mcpServers": {
    "cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
      "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
    }
  }
}

Escreva o cabeçalho sem espaço após os dois-pontos e coloque o valor inteiro na variável de ambiente, conforme acima.

Reinicie o cliente e peça para ele listar suas ferramentas.

Verifique a conexão sem um cliente:

bash

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

Como funciona

Item	Detalhe
Endpoint	`POST /mcp` com uma mensagem JSON-RPC 2.0; a resposta é `application/json`. `GET /mcp` responde 405 (sem fluxo de servidor para cliente); `DELETE /mcp` encerra a sessão.
Autenticação	Apenas `Authorization: Bearer vk_...` (tokens de sessão, cookies e chaves de admin são recusados com 401 e um cabeçalho `WWW-Authenticate: Bearer`).
Sessão	`Mcp-Session-Id` é emitido por `initialize`, vinculado a essa chave, válido por 24 horas; no máximo 16 sessões por chave.
Ferramentas	Uma por operação de API pública visível para a chave. O nome da ferramenta é o comando CLI com `_` em vez de espaços e traços (`vm firewall add` vira `vm_firewall_add`) e equivale ao `operationId` da OpenAPI. Uma ferramenta é listada apenas quando a chave possui o escopo dela e o módulo está ativado.
Capacidades	Apenas ferramentas (sem recursos ou prompts).
Tamanho	Corpo da requisição de até 1 MB; texto de resultado de ferramenta de até cerca de 100 KB (o excedente é cortado com uma observação); uma chamada leva no máximo 55 segundos.

Regras de segurança

Mesmo portão do REST. Cada tools/call passa pelo pipeline de requisições próprio do painel: escopo, site, restrição de IP, limite de taxa, idempotência, verificações de propriedade (404 para recursos de terceiros) e cotas se aplicam. O MCP não pode conceder nada que a chave não possua.
Confirmação. Ferramentas que cobram, excluem ou retornam credenciais (tickets de console, kubeconfig, segredos S3 ou SSH, redefinições de senha, novas chaves) exigem o argumento confirm: true. A descrição da ferramenta instrui o assistente a repassá-lo apenas após a aprovação do usuário, de modo que uma instrução oculta em uma página da web ou log não possa acioná-la por conta própria.
Idempotência. Ferramentas pagas aceitam idempotency_key; se omitido, uma chave estável é derivada do nome da ferramenta e dos argumentos, para que uma nova tentativa idêntica não possa cobrar duas vezes.
Não expostos como ferramentas: endpoints de streaming (o chat do AI Agent), tickets únicos de SSH ou WebSocket de console, downloads binários e os endpoints do aplicativo VPN (/v1/ext/*).
Nunca possível: a API nunca permite recargas, alterações de senha, exclusão da conta ou criação de chaves, portanto nenhum assistente pode realizá-las.

Limites

Limite	Padrão
Chamadas de ferramenta por chave	60 por minuto
Requisições MCP por chave	240 por minuto
Mais os limites normais de chave e conta	Consulte REST API

Acima do limite, o endpoint responde com HTTP 429 com um erro JSON-RPC e Retry-After.

Verificar

O comando curl acima retorna um resultado JSON-RPC com uma lista tools. Apenas as ferramentas que correspondem aos escopos da chave aparecem.
No seu cliente, pergunte "list my VMs": o assistente chama vm_list e exibe o resultado.
No portal, o horário de Last used da chave é atualizado, e as chamadas de gravação aparecem no Key usage log.

Limites e notas

Login pelo navegador (OAuth). A página de referência também descreve a autenticação pelo navegador para clientes que oferecem suporte ao OAuth do MCP. Em uma instalação do NexCMP, o método suportado e testado é a chave de API (ou cmp login para o CLI).
Sites de revendedores não exibem a seção MCP; os clientes deles usam o domínio do revendedor para a API.
Menor privilégio. Crie uma chave dedicada por assistente com escopos de leitura primeiro; adicione escopos de gravação apenas quando necessário.
Revogue a chave em API keys para cortar o acesso do assistente imediatamente.

Resolução de problemas

Sintoma	Causa	Correção
401 com `WWW-Authenticate: Bearer`	Sem chave, chave incorreta ou token de sessão	Envie `Authorization: Bearer vk_...`.
403 sobre `Origin`	Uma página de navegador em outra origem	Use um cliente de desktop ou CLI; ou peça ao administrador para permitir a origem (`mcp_allowed_origins`).
404 em uma requisição com `Mcp-Session-Id`	A sessão pertence a outra chave ou expirou	Execute `initialize` novamente.
405 em `GET /mcp`	Esperado: o servidor não possui fluxo de eventos	Use apenas POST (os clientes fazem isso automaticamente).
A lista de ferramentas é curta	Escopos de chave ou módulos	Adicione escopos à chave; habilite o módulo.
A ferramenta responde que precisa de `confirm: true`	Ferramenta paga, de exclusão ou sensível	O assistente deve definir `confirm` após a sua aprovação.
429	Limite de taxa do MCP ou da chave	Aguarde `Retry-After`.
O cliente não consegue se conectar com um cabeçalho	Cliente sem suporte a cabeçalho personalizado	Use a ponte `mcp-remote`.

Servidor MCP ​

O que faz ​

Requisitos ​

Preparar a infraestrutura ​

Conectar (lado do cliente) ​

Como funciona ​

Regras de segurança ​

Limites ​

Verificar ​

Limites e notas ​

Resolução de problemas ​