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
| Item | Valor |
|---|---|
| URL | https://<instancia>/api/mcp/v1 |
| Método | POST |
| Transporte | Streamable HTTP, sem estado (stateless): um objeto JSON-RPC por requisição |
| Métodos suportados | initialize, ping, tools/list, tools/call |
| Protocolo | 2025-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
senhadoresumo); 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_assinantedas 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
| Ferramenta | Nome exibido | Tipo | Descrição |
|---|---|---|---|
acs_get_cpe | Consultar equipamento | Leitura | Redes Wi-Fi (nome, faixa, no ar ou não), band steering, EasyMesh e aparelhos conectados. |
acs_update_wifi | Alterar Wi-Fi | Escrita | Altera nome, senha, canal, largura de canal, liga/desliga redes Wi-Fi, band steering e EasyMesh. |
acs_reboot_cpe | Reiniciar equipamento | Escrita | Solicita o reinício do equipamento. |
acs_diagnostic_start | Testar equipamento | Escrita | Inicia um diagnóstico no equipamento: ping, traceroute, teste de velocidade ou análise do Wi-Fi. |
acs_diagnostic_result | Resultado do teste | Leitura | Lê 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:
| Campo | Descrição |
|---|---|
serial_number | Número de série do equipamento. |
mac_address | Endereço MAC do equipamento. |
pppoe_username | Usuá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:
| Campo | Descrição |
|---|---|
resumo | Bloco para o chat falar com o assinante (veja abaixo). |
device | Dados 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_settings | Band 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:
| Campo | Descrição |
|---|---|
modelo | Fabricante 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_ligado | Band steering do aparelho ligado ou não. |
easymesh_ligado | EasyMesh do aparelho ligado ou não. |
aparelhos_conectados_por_cabo | Aparelhos ativos que não estão em nenhuma rede Wi-Fi. |
aparelhos_conectados | Total 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:
| Campo | Regra |
|---|---|
ssid | Nome da rede, até 32 caracteres. |
password | De 8 a 63 caracteres, dentro da política de senha do sistema. |
channel | Número inteiro; 0 = automático. |
enabled | true liga e false desliga a rede. |
bandwidth | Largura 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:
| Campo | Regra |
|---|---|
band_steering | true liga e false desliga o band steering do aparelho. |
easymesh | true 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:
| Campo | Descrição |
|---|---|
mensagem_assinante | Mensagem pronta, em português formal, para o assinante. |
aplicada_no_equipamento | Sempre 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_afetados | Aparelhos 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:
| Campo | Descrição |
|---|---|
mensagem_assinante | Mensagem pronta: a internet ficará indisponível por alguns minutos e volta sozinha. |
aplicado_no_equipamento | Sempre 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_conectados | Aparelhos 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.
type | O que faz | Campos |
|---|---|---|
ping | Testa 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) |
traceroute | Mostra 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) |
speedtest | Mede 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_survey | Analisa 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:
| Campo | Descrição |
|---|---|
status | concluido, em_andamento ou nao_concluido (na análise do Wi-Fi: concluida, em_andamento ou nao_concluida). |
mensagem_assinante | Mensagem pronta, em português formal, para o assinante. |
resumo | Os números do teste, para o chat falar com o assinante (tabela abaixo). |
id_do_diagnostico | Só com em_andamento. Uso interno: serve para chamar acs_diagnostic_result. |
motivo | Só 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_assistente | Opcional. Orientação ao modelo; não deve ser repassada ao assinante. |
type | Campos do resumo |
|---|---|
ping | tentativas, respostas, perda_percentual, tempo_medio_ms |
traceroute | chegou_ao_destino, etapas |
speedtest | download_mbps, upload_mbps (null quando o modelo mede só o download) |
site_survey | Uma 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:
| Campo | Descrição |
|---|---|
mensagem_assinante | Frase pronta para o assinante. |
motivo | Código estável do erro (tabela abaixo). |
detalhe_para_o_assistente | Opcional. Ajuda o modelo a corrigir a chamada; não deve ser repassado ao assinante. |
motivo | Quando acontece |
|---|---|
equipamento_nao_encontrado | Equipamento não encontrado com os dados informados. |
sem_dados_do_equipamento | Ainda não há leitura do equipamento; consulte antes com acs_get_cpe. |
dados_invalidos | Entrada inválida (por exemplo, mais de um identificador). |
senha_fora_dos_requisitos | A nova senha não atende à política de senha. |
nao_suportado_pelo_modelo | O modelo não permite a alteração ou o teste pedido. |
reinicio_ja_solicitado | Limite de reinícios excedido. |
diagnostico_em_andamento | Já existe um diagnóstico em andamento no equipamento. |
teste_ja_solicitado | Limite de diagnósticos por minuto excedido. |
teste_nao_encontrado | id_do_diagnostico desconhecido ou expirado (24 horas). |
comando_nao_aceito | O ACS não aceitou o comando agora. |
sistema_indisponivel | ACS indisponível. |
erro_inesperado | Qualquer 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_wifipassa 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>.