---
title: Conectar um cliente de IA (MCP)
description: Conecte Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai, ChatGPT e SDKs OpenAI ao endpoint MCP de admin com a lista de ferramentas.
url: https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Conectar um cliente de IA (MCP) {#connect-an-ai-client-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 {#what-it-does}

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.

::: info Dois endpoints MCP
`/mcp` é o endpoint de **clientes** (chaves de API de clientes, `vk_`; consulte [MCP server](https://nexcmp.com/pt/docs/developers/mcp/)). `/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 {#requirements}

| 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](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/) (`ak_...`) com os escopos desejados, **ou** login OAuth para conectores web ([OAuth connectors](https://nexcmp.com/pt/docs/configure-with-ai/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 {#prepare-the-infrastructure}

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:

```bash
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 {#connect-in-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](https://nexcmp.com/pt/docs/configure-with-ai/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.

![Aba Connect an AI com a URL MCP e um cartão com botão de cópia por cliente](https://nexcmp.com/pt/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

```bash
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 {#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:

```json
{
  "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) {#claude-ai-custom-connector}

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](https://nexcmp.com/pt/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (modo de desenvolvedor) {#chatgpt-developer-mode}

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](https://nexcmp.com/pt/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

Adicionar a `~/.codex/config.toml`:

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

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

::: tip 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 {#gemini-cli}

Adicionar a `~/.gemini/settings.json`:

```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 {#cursor}

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

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

::: tip 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) {#openai-agents-sdk-python}

```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`):

```python
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 {#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:

```json
{
  "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) {#anything-else-plain-http}

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 {#verify}

1. Sem um cliente, liste as ferramentas:

   ```bash
   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 {#tools}

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](#confirmation-confirm-token)). 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 {#overview-and-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 {#settings-branding-legal-modules}

| 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 {#email-and-alerts}

| 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 {#payments-and-currency}

| 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 {#infrastructure-and-zones}

| 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 {#catalog-and-plans}

| 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 {#customers-and-resellers}

| 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 {#ai-provider}

| 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 {#configuration-files}

| 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](https://nexcmp.com/pt/docs/configure-with-ai/config-as-code/) para ver o formato do arquivo.

## Prompts {#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`) {#confirmation-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.

::: warning 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 {#how-it-works}

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

- 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](https://nexcmp.com/pt/docs/configure-with-ai/ai-chat-in-admin/#secrets)) ou referências `secret://` ([Configuration as code](https://nexcmp.com/pt/docs/configure-with-ai/config-as-code/#secrets)).
- 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 {#troubleshooting}

| 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](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/#errors).