MCP para integradores

Servidor MCP da instância para conectar o chat de atendimento ao ACS com o token da API externa, voltado ao assinante final.

MCP para integradores

O MCP (Model Context Protocol) é um protocolo aberto que permite a chatbots e agentes de IA chamarem ferramentas de um sistema. A instância do Made4Graph expõe um servidor MCP que dá acesso ao equipamento do assinante no ACS (consultar, alterar Wi-Fi, reiniciar e fazer diagnósticos: ping, traceroute, teste de velocidade e análise do Wi-Fi), com as mesmas regras de autenticação, licença, limite e auditoria da API externa.

O servidor foi pensado para um chat que conversa direto com o assinante final. As instruções e as descrições das ferramentas estão em português, e as respostas já trazem uma mensagem pronta para o assinante, sem termos técnicos.

Cada provedor roda a sua própria instância e usa o token do seu próprio usuário de integração: não há compartilhamento entre provedores.

Endpoint

ItemValor
URLhttps://<instancia>/api/mcp/v1
MétodoPOST
TransporteStreamable HTTP, sem estado (stateless): um objeto JSON-RPC por requisição
Métodos suportadosinitialize, ping, tools/list, tools/call
Protocolo2025-06-18 (padrão), 2025-03-26 e 2024-11-05

GET e DELETE retornam 405. Requisições em lote (batch) não são aceitas. Use sempre HTTPS.

Autenticação e licença

  • Envie o header Authorization: Bearer <token> com o mesmo token da API externa do usuário (veja Usuários).
  • O usuário precisa ter a API externa habilitada.
  • O módulo ACS precisa estar licenciado na instância (veja Licença). Não existe licença própria do MCP.

Se o token estiver ausente ou inválido, ou o usuário não tiver a API externa habilitada, a própria requisição volta com HTTP 401. Sem a licença do ACS, volta com HTTP 403. Nos dois casos não é erro de ferramenta: a resposta HTTP vem antes de qualquer chamada.

Como o chat deve se comportar

No initialize, o servidor envia ao cliente MCP instruções em português para o modelo do chat. Em resumo, elas pedem que o chat:

  • fale com o assinante em português formal, simples e cordial, sem termos técnicos (nada de "ACS", "CPE", "SSID", "PPPoE" ou "índice da rede");
  • nunca mostre serial, MAC, IP, índices de rede nem códigos de erro;
  • se o assinante pedir a senha atual do Wi-Fi, informe a senha da rede pedida (campo senha do resumo); se ela vier vazia, explique que o equipamento não informa a senha e ofereça trocar por uma nova;
  • confirme com o assinante antes de alterar o Wi-Fi, reiniciar ou fazer um teste no equipamento e só chame a ferramenta depois de um "sim" claro;
  • use a mensagem_assinante das respostas e nunca diga que a alteração ou o reinício já foi concluído, porque o equipamento ainda vai aplicar.

A confirmação com o assinante é uma orientação dada ao modelo, não uma trava do servidor. Veja Segurança.

Ferramentas

FerramentaNome exibidoTipoDescrição
acs_get_cpeConsultar equipamentoLeituraRedes Wi-Fi (nome, faixa, no ar ou não), band steering, EasyMesh e aparelhos conectados.
acs_update_wifiAlterar Wi-FiEscritaAltera nome, senha, canal, largura de canal, liga/desliga redes Wi-Fi, band steering e EasyMesh.
acs_reboot_cpeReiniciar equipamentoEscritaSolicita o reinício do equipamento.
acs_diagnostic_startTestar equipamentoEscritaInicia um diagnóstico no equipamento: ping, traceroute, teste de velocidade ou análise do Wi-Fi.
acs_diagnostic_resultResultado do testeLeituraLê o resultado de um diagnóstico iniciado por acs_diagnostic_start.

Identificador do equipamento

Todas as ferramentas recebem o identificador no corpo da chamada, e você deve informar exatamente um destes campos:

CampoDescrição
serial_numberNúmero de série do equipamento.
mac_addressEndereço MAC do equipamento.
pppoe_usernameUsuário PPPoE do assinante.

Informar nenhum ou mais de um volta como erro (dados_invalidos). Esses dados são de uso interno e não devem ser repetidos ao assinante.

acs_get_cpe

Entrada: um identificador (veja acima).

Saída:

CampoDescrição
resumoBloco para o chat falar com o assinante (veja abaixo).
deviceDados do equipamento, incluindo serial, MAC e IP (uso interno).
wifi[]Redes Wi-Fi: index, band, ssid, password, channel, enabled, broadcasting, merged_by_band_steering etc. O index serve só para chamar acs_update_wifi.
wifi_settingsBand steering e EasyMesh do aparelho: { "band_steering": { "enabled": true }, "easymesh": { "enabled": false } }.
hosts[]Aparelhos conectados, com wlan_index quando vierem por Wi-Fi.

O bloco resumo traz:

CampoDescrição
modeloFabricante e modelo do equipamento.
redes_wifi[]Para cada rede: nome, faixa (por exemplo, 2,4 GHz), ligada (a rede está no ar), unida_pelo_band_steering, senha e aparelhos_conectados.
band_steering_ligadoBand steering do aparelho ligado ou não.
easymesh_ligadoEasyMesh do aparelho ligado ou não.
aparelhos_conectados_por_caboAparelhos ativos que não estão em nenhuma rede Wi-Fi.
aparelhos_conectadosTotal de aparelhos ativos.

A senha do Wi-Fi é devolvida (senha no resumo e password em wifi[]) quando o equipamento a informa. Em equipamentos que não informam a senha, ela vem vazia (null). Cada consulta fica registrada na Auditoria como visualização de senha (wifi_password_view), sem a senha. Os dados são os da última leitura do equipamento e não indicam se ele está ligado agora.

Band steering e EasyMesh: wifi_settings traz o valor do aparelho, o mesmo do painel. Cada chave só aparece quando o modelo suporta e o parâmetro é editável; senão fica ausente (nunca null), e sem nenhuma chave o bloco é {}. Com o band steering ligado, a rede 5 GHz unida à 2,4 GHz vem com broadcasting: false e merged_by_band_steering: true: o número de redes no ar bate com o painel. Para isso funcionar, a CPE precisa ser reprocessada depois da atualização do sistema; até lá as duas redes aparecem no ar.

Mudança de contrato: os campos band_steering e easymesh por rede, dentro de wifi[], foram removidos. Use wifi_settings.

Se o equipamento nunca foi aberto no sistema, a primeira consulta faz a leitura completa dele e, conforme a configuração do servidor, pode executar diagnósticos no equipamento (ping, marcação e gravação de parâmetros). Por isso a ferramenta não é anunciada como somente leitura. As consultas seguintes só leem os dados já guardados.

acs_update_wifi

Entrada: um identificador e networks, um objeto indexado pelo index devolvido por acs_get_cpe. Envie só o que muda. networks é opcional quando vier band_steering ou easymesh. Campos aceitos por rede:

CampoRegra
ssidNome da rede, até 32 caracteres.
passwordDe 8 a 63 caracteres, dentro da política de senha do sistema.
channelNúmero inteiro; 0 = automático.
enabledtrue liga e false desliga a rede.
bandwidthLargura de canal. Só aceita os valores que o modelo lista para a rede (sem diferenciar maiúsculas de minúsculas; inclui Auto).

No nível do aparelho, fora de networks:

CampoRegra
band_steeringtrue liga e false desliga o band steering do aparelho.
easymeshtrue liga e false desliga o EasyMesh do aparelho.
{
  "serial_number": "ABC123456789",
  "networks": {
    "1": { "ssid": "MinhaRede", "password": "senha-forte-123" },
    "5": { "channel": 36, "bandwidth": "80MHz" }
  },
  "band_steering": true
}

Ligar ou desligar o band steering ou o EasyMesh mexe no Wi-Fi inteiro da CPE (o EasyMesh pode criar uma rede de backhaul). Tudo vai numa única alteração no ACS. Se o modelo não suportar, o parâmetro for somente leitura ou a largura não estiver na lista do modelo, a ferramenta responde 422 e nada é enviado à CPE (por exemplo, This device model does not support band_steering. ou networks.5.bandwidth must be one of: ...). A auditoria registra os campos alterados (device.band_steering, device.easymesh, <índice>.bandwidth), sem os valores.

Saída:

CampoDescrição
mensagem_assinanteMensagem pronta, em português formal, para o assinante.
aplicada_no_equipamentoSempre false: o equipamento aplica a alteração em alguns minutos.
redes[]Por rede: rede, faixa, alteracoes_enviadas, nao_suportado_pelo_modelo e aparelhos_conectados.
aparelhos_conectados_afetadosAparelhos que estavam conectados nas redes alteradas, pela última leitura. Pode ser null se não houver leitura.

Alterações que o modelo não permite não são enviadas e aparecem em nao_suportado_pelo_modelo, com uma frase explicando na mensagem_assinante. Senha fora dos requisitos é recusada e volta como erro (senha_fora_dos_requisitos).

task_id e cpe_id não são devolvidos pelo MCP. Eles ficam registrados na Auditoria.

acs_reboot_cpe

Entrada: um identificador.

Saída:

CampoDescrição
mensagem_assinanteMensagem pronta: a internet ficará indisponível por alguns minutos e volta sozinha.
aplicado_no_equipamentoSempre false: aceito não significa reiniciado. Se o equipamento não reiniciar de imediato, o reinício acontece quando ele voltar a se comunicar com o sistema.
aparelhos_conectadosAparelhos que estavam conectados, pela última leitura. Pode ser null.

Limite: 5 reinícios por minuto por token, compartilhado com a API externa. Acima disso a chamada volta com o motivo reinicio_ja_solicitado.

acs_diagnostic_start

Executa um diagnóstico no equipamento do assinante. Entrada: um identificador, o type e os campos do tipo.

typeO que fazCampos
pingTesta a conexão do equipamento até um endereço e informa perda e tempo de resposta.host (obrigatório), count (1 a 20, padrão 4), timeout_seconds (1 a 10, padrão 5)
tracerouteMostra o caminho (saltos) da conexão até um endereço, para localizar lentidão ou perda.host (obrigatório), max_hops (1 a 30, padrão 30)
speedtestMede download e upload a partir do próprio equipamento, até o servidor do provedor. Ocupa a conexão durante a medição. O upload só roda depois de um download concluído.file_size (5mb, 10mb, 50mb ou 100mb, padrão 10mb)
site_surveyAnalisa as redes Wi-Fi vizinhas e indica o canal mais livre em cada faixa. Em alguns modelos o Wi-Fi pode oscilar por alguns segundos.—
{
  "serial_number": "ABC123456789",
  "type": "ping",
  "host": "8.8.8.8"
}

Antes de enviar qualquer coisa ao equipamento, o servidor confere se o modelo permite o teste. Se não permitir, a chamada já volta com o motivo nao_suportado_pelo_modelo, sem tocar no equipamento.

O teste leva de alguns segundos a alguns minutos. A chamada espera até 20 segundos pelo resultado. Se ele não ficar pronto nesse tempo, a resposta vem com status em_andamento e o id_do_diagnostico, que o chat usa em acs_diagnostic_result.

Saída:

CampoDescrição
statusconcluido, em_andamento ou nao_concluido (na análise do Wi-Fi: concluida, em_andamento ou nao_concluida).
mensagem_assinanteMensagem pronta, em português formal, para o assinante.
resumoOs números do teste, para o chat falar com o assinante (tabela abaixo).
id_do_diagnosticoSó com em_andamento. Uso interno: serve para chamar acs_diagnostic_result.
motivoSó quando não concluído: teste_nao_concluido, teste_sem_resposta ou nao_suportado_pelo_modelo; na análise do Wi-Fi, analise_nao_concluida ou analise_sem_resposta.
detalhe_para_o_assistenteOpcional. Orientação ao modelo; não deve ser repassada ao assinante.
typeCampos do resumo
pingtentativas, respostas, perda_percentual, tempo_medio_ms
traceroutechegou_ao_destino, etapas
speedtestdownload_mbps, upload_mbps (null quando o modelo mede só o download)
site_surveyUma entrada por faixa: faixa, redes_vizinhas, canal_atual, canal_automatico, canal_recomendado, troca_recomendada, redes_no_canal_atual e redes_no_canal_recomendado

Os nomes das redes vizinhas nunca são devolvidos: elas são de outras pessoas. A análise do Wi-Fi não troca o canal; para trocar, o chat usa acs_update_wifi depois da confirmação do assinante.

Limites: um diagnóstico por vez no equipamento (outro em andamento volta com diagnostico_em_andamento) e 5 inícios por minuto por token, somando todos os tipos e compartilhados com a API externa (acima disso, teste_ja_solicitado).

acs_diagnostic_result

Entrada: id_do_diagnostico, devolvido por acs_diagnostic_start.

Espera até 20 segundos se o teste ainda estiver em andamento e responde no mesmo formato de acs_diagnostic_start. Se vier de novo em_andamento, o chat avisa o assinante e chama outra vez. Um id desconhecido ou com mais de 24 horas volta com teste_nao_encontrado.

Erros

Falhas voltam como erro de ferramenta (isError: true), sempre com uma frase para o assinante e sem detalhes internos:

CampoDescrição
mensagem_assinanteFrase pronta para o assinante.
motivoCódigo estável do erro (tabela abaixo).
detalhe_para_o_assistenteOpcional. Ajuda o modelo a corrigir a chamada; não deve ser repassado ao assinante.
motivoQuando acontece
equipamento_nao_encontradoEquipamento não encontrado com os dados informados.
sem_dados_do_equipamentoAinda não há leitura do equipamento; consulte antes com acs_get_cpe.
dados_invalidosEntrada inválida (por exemplo, mais de um identificador).
senha_fora_dos_requisitosA nova senha não atende à política de senha.
nao_suportado_pelo_modeloO modelo não permite a alteração ou o teste pedido.
reinicio_ja_solicitadoLimite de reinícios excedido.
diagnostico_em_andamentoJá existe um diagnóstico em andamento no equipamento.
teste_ja_solicitadoLimite de diagnósticos por minuto excedido.
teste_nao_encontradoid_do_diagnostico desconhecido ou expirado (24 horas).
comando_nao_aceitoO ACS não aceitou o comando agora.
sistema_indisponivelACS indisponível.
erro_inesperadoQualquer outra falha.

Problemas do protocolo (JSON inválido, método ou ferramenta desconhecida) voltam como erro JSON-RPC, e falhas de autenticação ou licença (HTTP 401 e 403) voltam como erro HTTP. Nenhum desses é erro de ferramenta.

Auditoria

Consultas com a senha do Wi-Fi (wifi_password_view), alterações de Wi-Fi e reinícios feitos pelo MCP são auditados contra o usuário do token, com a origem mcp (a API externa direta usa external_api). Na auditoria ficam o cpe_id (nas duas ações) e o task_id (só nas alterações de Wi-Fi; o reinício não tem task_id). A senha Wi-Fi não é gravada no registro. Veja Auditoria.

Segurança

As ações de escrita (acs_update_wifi, acs_reboot_cpe e acs_diagnostic_start) não têm trava de confirmação no servidor. O pedido de confirmação ao assinante vem das instruções e das descrições enviadas ao modelo, e a aprovação final é responsabilidade do provedor e do cliente MCP utilizado. Configure o seu cliente para exigir aprovação nas ferramentas de escrita.

  • Trate o token como senha e use HTTPS.
  • A senha digitada pelo assinante em um pedido de acs_update_wifi passa pelo histórico do chat. Considere isso antes de usá-la.
  • Se desconfiar de vazamento, regenere o token do usuário em Usuários.

Configurar o cliente

Os exemplos usam um token fictício. Substitua pelo token real do usuário e <instancia> pelo endereço da sua instância.

Claude Code

claude mcp add --transport http made4graph https://<instancia>/api/mcp/v1 \
  --header 'Authorization: Bearer m4g_exemplo_token_ficticio'

Claude Desktop

Para clientes que só falam com servidores locais, use a ponte mcp-remote no arquivo de configuração:

{
  "mcpServers": {
    "made4graph": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<instancia>/api/mcp/v1",
        "--header",
        "Authorization: Bearer m4g_exemplo_token_ficticio"
      ]
    }
  }
}

Outros clientes

Qualquer cliente MCP compatível com Streamable HTTP funciona: informe a URL do endpoint e o header Authorization: Bearer <token>.

Nesta página