Conectar o Packetrove a um agente de IA
Conecte um cliente MCP compatível para usar as ferramentas de rede do Packetrove. Comece pela configuração abaixo e consulte os exemplos.
Streamable HTTP · Sem conta nem chave de API
https://api.staging.packetrove.com/mcp
Conectar seu cliente
Com o Claude Code ou o Codex instalado, adicione este servidor remoto. Os comandos configuram o cliente; eles não instalam um servidor Packetrove local.
Claude Code
claude mcp add --transport http --scope user packetrove \ https://api.staging.packetrove.com/mcpDocumentação MCP do Claude Code
Codex
codex mcp add packetrove \ --url https://api.staging.packetrove.com/mcpDocumentação MCP do Codex
Use /mcp no cliente para verificar a conexão. Confirme que estas ferramentas estão disponíveis: cidr-cover, cidr-subtract, range-to-cidrs, certificate-bundle, public-ip.
Após a configuração, o cliente descobre as ferramentas com tools/list. As descrições e os esquemas orientam a escolha e os argumentos. Ler uma página web não configura um cliente nem dá acesso às ferramentas.
Identidade do servidor
O servidor apresenta a seguinte identidade do serviço, com sua versão publicada. Nomes, descrições e esquemas de cada ferramenta são listados separadamente por tools/list.
{
"name": "Packetrove",
"title": "Packetrove",
"description": "Open-source IP address and CIDR tools for network calculations and public IP lookup.",
"websiteUrl": "https://staging.packetrove.com",
"icons": [
{
"src": "https://staging.packetrove.com/packetrove-logo-32x32.png",
"mimeType": "image/png",
"sizes": [
"32x32"
]
}
],
"version": "0.5.0"
}Os clientes decidem se exibem o título, a descrição, o site ou o ícone e podem ignorar os campos opcionais. A descoberta bem-sucedida do protocolo não comprova que um cliente exiba essas informações. O ícone PNG tem 32×32 e não possui restrição de tema.
Ler resultados e tratar erros
Leia structuredContent ou o JSON do bloco de texto. Mantenha as contagens como strings decimais ou inteiros de precisão arbitrária; converter grandes contagens IPv6 em números de ponto flutuante perde precisão.
As respostas bem-sucedidas mantêm o resultado em structuredContent e no primeiro bloco de texto JSON, e acrescentam um resource_link opcional para a página da ferramenta em inglês. Os links não contêm entradas nem resultados e não restauram o cálculo. Cada cliente decide se exibe, ignora ou abre os links; a exibição ou citação automática não é garantida. Abrir a página de IP público verifica uma nova conexão do navegador, que pode ser diferente da conexão do cliente MCP. Os erros não incluem links da ferramenta.
Se isError for true, leia o JSON do erro antes de tentar novamente. Corrija INVALID_INPUT e MIXED_ADDRESS_FAMILIES com as informações do usuário. CLIENT_IP_UNAVAILABLE indica que faltam metadados confiáveis da conexão; não invente um endereço.
Erros de negócio usam o JSON de erro compartilhado. O SDK MCP valida o protocolo. JSON inválido, tipos de conteúdo não suportados e corpos muito grandes são rejeitados na camada HTTP.
Executar um exemplo Node.js
Em um novo diretório, salve o código como packetrove-example.mjs e execute os comandos. O exemplo usa @modelcontextprotocol/client@2.0.0, descobre ferramentas e chama a ferramenta CIDR com endereços de documentação.
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
const client = new Client(
{ name: 'packetrove-example', version: "0.5.0" },
{ versionNegotiation: { mode: 'auto' } },
);
try {
await client.connect(new StreamableHTTPClientTransport(new URL("https://api.staging.packetrove.com/mcp")));
const serverInfo = client.getServerVersion();
const { tools } = await client.listTools();
const result = await client.callTool({
name: "cidr-cover",
arguments: {"inputs":["203.0.113.1","203.0.113.2","203.0.113.6"]},
});
if (result.isError) throw new Error(JSON.stringify(result.content));
console.log(serverInfo, tools.map(tool => tool.name), result.structuredContent);
const links = result.content?.filter(content => content.type === 'resource_link') ?? [];
console.log(links); // Optional links; opening or presenting them is the client's choice.
} finally {
await client.close();
}npm init -y npm install @modelcontextprotocol/client@2.0.0 node packetrove-example.mjs
Para desenvolvimento local, inicie pnpm dev:api e substitua a URL do servidor por http://localhost:8787/mcp.
Implantação e limites de conexão
O servidor aceita solicitações modernas sem estado e inicialização, descoberta e chamadas do Streamable HTTP anterior. Não oferece sessões persistentes nem fluxos de eventos independentes do servidor.
Os metadados de IP público são lidos em cada chamada, com instâncias isoladas entre clientes simultâneos. Resultados e erros MCP usam Cache-Control: no-store, no-transform. O aplicativo não armazena nem registra endereços consultados.
Contamos execuções com eventos operacionais que contêm o nome da ferramenta, sucesso ou erro, um código de erro controlado e uma classificação da origem da chamada. Verificações automatizadas validadas também podem registrar um identificador de execução da automação. Entradas, resultados, endereços consultados, cabeçalhos brutos da solicitação e tokens de automação são excluídos. A Cloudflare pode adicionar metadados da solicitação; veja a política de privacidade para tratamento e retenção.
Os nomes anteriores não têm aliases de compatibilidade: smallest_covering_cidr → cidr-cover, subtract_cidrs → cidr-subtract, get_public_ip → public-ip. Atualize a descoberta de ferramentas e as chamadas salvas.
O caminho /mcp do site não é o serviço: GET retorna 404 e POST 405, sem proxy ou redirecionamento. Configure os clientes com https://api.staging.packetrove.com/mcp. Na sua implantação, atualize domínios e listas exatas separadas de Host e Origin do navegador; clientes sem cabeçalho Origin são aceitos.