---
title: Servidor MCP
description: Conecte assistentes de IA (Claude, Cursor, VS Code e mais) à API via endpoint MCP em /mcp: autenticação, configuração, ferramentas e regras de segurança.
url: https://nexcmp.com/pt/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Servidor MCP {#mcp-server}

> **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 {#what-it-does}

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.

::: tip 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](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/) (endpoint `/mcp/admin`, chaves de admin `ak_`).
:::

## Requisitos {#requirements}

| 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](https://nexcmp.com/pt/docs/developers/api-keys/) (`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 {#prepare-the-infrastructure}

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) {#connect-customer-side}

1. 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.
2. 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.

3. 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 {#how-it-works}

| 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 {#safety-rules}

- **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 {#limits}

| 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](https://nexcmp.com/pt/docs/developers/api/#rate-limits) |

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

## Verificar {#verify}

1. O comando `curl` acima retorna um resultado JSON-RPC com uma lista `tools`. Apenas as ferramentas que correspondem aos escopos da chave aparecem.
2. No seu cliente, pergunte "list my VMs": o assistente chama `vm_list` e exibe o resultado.
3. 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 {#limits-notes}

- **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 {#troubleshooting}

| 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`. |