Como Conectar o Agente Pi à Web: Guia de Integração do Servidor MCP Sem Raspagem

Principais Conclusões:

• O Agente Pi é um agente de codificação baseado em terminal, deliberadamente minimalista. Ele vem com quatro ferramentas (read, write, edit, bash) e adiciona tudo o mais por meio de extensões opcionais, o que mantém a janela de contexto pequena, mas significa que o acesso à web não está embutido.
• O pi-mcp-adapter conecta o Pi a qualquer servidor MCP através de uma única ferramenta proxy de ~200 tokens. Os servidores são preguiçosos por padrão — eles só começam quando o agente chama uma de suas ferramentas — então conectar vários servidores MCP não estoura o orçamento de contexto.
• O Servidor MCP Scrapeless expõe 21 ferramentas via stdio e através de um endpoint HTTP streamável em https://api.scrapeless.com/mcp. A cobertura abrange google_search, google_trends, a superfície completa de 16 ferramentas browser_* (um navegador anti-deteção hospedado na nuvem com proxies residenciais em mais de 195 países) e três ferramentas de scraping sem estado (scrape_html, scrape_markdown, scrape_screenshot).
• Um arquivo .mcp.json conecta o Pi ao Scrapeless. O adaptador lê o formato de configuração MCP padrão que o Claude Desktop, Cursor e outros clientes MCP já utilizam, então o mesmo trecho JSON pode ser usado em qualquer um deles.
• O padrão de ponta a ponta: prompt → Pi → pi-mcp-adapter → scrapeless-mcp-server → navegador em nuvem → resultados classificados ou Markdown extraído → código gerado com dados ao vivo. O Pi para de gerar a partir do conhecimento apenas de treinamento e começa a fundamentar a saída na página que acabou de raspar.
• Gratuito para começar. Novas contas do Scrapeless incluem o tempo de execução gratuito do Scraping Browser — inscreva-se em app.scrapeless.com.

Introdução: um agente de codificação minimalista com ferramentas web ao vivo

A maioria dos agentes de codificação em terminal vem com dezenas de recursos que você pode nunca usar. O Agente Pi adota a posição oposta: quatro ferramentas, total transparência, tudo o mais adicionado sob demanda. Isso mantém o agente rápido e a janela de contexto barata, mas também significa que o Pi não pode buscar a documentação mais recente de uma biblioteca, ler uma página de lançamento que foi publicada na semana passada ou puxar dados ao vivo de uma página da web pública por conta própria.

A solução é conectar o Pi a um servidor do Protocolo de Contexto de Modelo (MCP) que expõe ferramentas da web. O pacote scrapeless-mcp-server faz exatamente isso — apoiado pelo Scrapeless Scraping Browser, um navegador anti-deteção hospedado na nuvem que se conecta por meio de proxies residenciais em mais de 195 países.

Este post explica como conectar os dois usando pi-mcp-adapter (a extensão comunitária MCP para o Pi) e um único arquivo .mcp.json. O endpoint ao qual o Pi se conecta é o mesmo que o Claude Desktop, Cursor e outros clientes MCP usam; o mesmo trecho JSON funciona em todos eles.

O Que Você Pode Fazer Com Isso

• Fundamentar a geração de código na documentação ao vivo. Faça com que o Pi busque o README atual de uma biblioteca antes de gerar um exemplo — não mais APIs desatualizadas do conhecimento de modelos cortados por treinamento.
• Pesquisar e raspar em uma única ação. O Pi chama google_search para classificar as páginas candidatas, depois scrape_markdown para puxar a mais relevante como Markdown limpa.
• Controlar um navegador em nuvem anti-deteção a partir de um prompt de terminal. Ferramentas como browser_goto, browser_click, browser_type e browser_get_html dão ao Pi controle total sobre um verdadeiro Chromium em nuvem com persistência de sessão.
• Puxar dados específicos da região através de proxies residenciais. Delimite uma pesquisa para gl=us ou gl=de diretamente a partir da chamada da ferramenta do agente.
• Ficar dentro de uma sessão de terminal. Sem troca de abas do navegador, sem copiar e colar a saída do curl, sem CLI de scraping separada para cuidar.

No Scrapeless, nós apenas acessamos dados publicamente disponíveis enquanto cumprimos estritamente com as leis, regulamentos e políticas de privacidade dos sites aplicáveis. O conteúdo deste post é apenas para fins de demonstração.

O Que é o Agente Pi?

Agente Pi é um agente de codificação baseado em terminal criado por Mario Zechner (o criador do framework de jogos libGDX). Fora da caixa, ele oferece ao modelo quatro ferramentas:

• read — ler arquivos e diretórios
• write — criar e editar arquivos
• edit — fazer edições específicas em arquivos existentes
• bash — executar comandos de shell

Tudo o mais é opcional. Você estende o Pi através de extensões em TypeScript, habilidades e templates de prompt agrupados como pacotes e instaláveis via npm ou git. O agente funciona em quatro modos — interativo (conversacional), print/JSON (scriptado), RPC (integração stdin/stdout) e SDK (embutido). O suporte do provedor é amplo: Anthropic, OpenAI, Google, Mistral, Groq e mais.

Instale globalmente com npm:

npm install -g @mariozechner/pi-coding-agent

A troca é explícita: uma superfície inicial pequena que você expande para se ajustar ao seu fluxo de trabalho, em vez de uma caixa de ferramentas que serve para todos.

Por Que o Pi Precisa de Acesso à Web

A razão do Pi é limitada pelo que o modelo subjacente foi treinado. Isso significa que ele não pode:

• Consultar as alterações mais recentes da API de uma biblioteca após o corte de treinamento
• Buscar páginas de documentação atuais, changelogs ou notas de lançamento
• Ler uma página pública para puxar uma tabela de configuração, um preço ou um esquema
• Verificar se um exemplo em seus dados de treinamento ainda compila com a versão do pacote de hoje

Para ecossistemas em rápida evolução — qualquer coisa web, frontend, ferramentas de IA, infraestrutura — isso é importante. Conecte o Pi a um servidor MCP com capacidade de web e você obtém um agente de codificação que procura informações atuais e raspa as páginas exatas que precisa antes de gerar código. A saída deixa de ser um melhor palpite de uma memória obsoleta e começa a ser baseada na página que acabou de ser renderizada.

O que é o Servidor MCP Scrapeless?

O Servidor MCP Scrapeless é um servidor do Protocolo de Contexto de Modelo que expõe o navegador cloud Scrapeless, APIs de busca e raspagem como ferramentas MCP. Qualquer cliente compatível com MCP — Pi, Claude Desktop, Cursor, Codex CLI, Gemini CLI, Windsurf, VS Code Copilot Chat — pode chamá-las diretamente de uma conversa.

No momento da publicação, o servidor expõe 21 ferramentas em três categorias:

• Busca e tendências — google_search, google_trends
• Automação de navegador (16 ferramentas) — browser_create, browser_close, browser_goto, browser_go_back, browser_go_forward, browser_click, browser_type, browser_press_key, browser_wait, browser_wait_for, browser_screenshot, browser_snapshot, browser_get_html, browser_get_text, browser_scroll, browser_scroll_to
• Raspagem sem estado — scrape_html, scrape_markdown, scrape_screenshot

Dois modos de transporte são suportados:

• Stdio — npx -y scrapeless-mcp-server executa o servidor como um processo filho do cliente MCP. Este é o padrão certo para agentes de desktop e terminal como o Pi.
• HTTP Streamable — aponte o cliente para https://api.scrapeless.com/mcp. Este é o padrão certo para agentes hospedados em nuvem que não podem executar npx.

Ambos os modos são suportados pela mesma chave de API Scrapeless. O código-fonte do servidor está em github.com/scrapeless-ai/scrapeless-mcp-server; referência completa de ferramentas em docs.scrapeless.com. Obtenha sua chave de API no plano gratuito em app.scrapeless.com.

A Ponte MCP: pi-mcp-adapter

O Pi não vem com suporte a MCP por padrão. Essa é uma escolha deliberada: Mario argumenta que as definições de ferramentas MCP são muito pesadas em tokens para um agente minimalista. Servidores MCP populares como Playwright MCP expõem 21 ferramentas e consomem cerca de 13,7k tokens; Chrome DevTools MCP expõe 26 ferramentas e consome cerca de 18k tokens. Conectar alguns servidores pode consumir uma parte significativa de uma janela de contexto antes que a conversa comece.

A resposta da comunidade é pi-mcp-adapter: uma extensão do Pi que expõe uma única ferramenta proxy (~200 tokens) em vez de carregar todas as definições de ferramentas MCP de uma vez. O agente busca e chama ferramentas individuais sob demanda:

mcp({ search: "screenshot" })
mcp({ tool: "scrapeless_scrape_markdown", args: '{"url": "https://example.com"}' })

Os servidores são preguiçosos por padrão — eles começam somente quando o agente chama pela primeira vez uma de suas ferramentas, e desconectam após 10 minutos de inatividade (configurável). Os metadados da ferramenta são armazenados em cache no disco, para que buscar e descrever funcionem sem conexões ativas.

O adaptador lê os arquivos de configuração padrão do MCP nesta ordem de precedência:

1. ~/.config/mcp/mcp.json (compartilhado global do usuário)
2. <diretório do agente Pi>/mcp.json (substituição global do Pi, tipicamente ~/.pi/agent/mcp.json)
3. .mcp.json (compartilhado local do projeto)
4. .pi/mcp.json (substituição do projeto Pi)

Instale-o com um comando (execute dentro do Pi ou via CLI do Pi):

pi install npm:pi-mcp-adapter

A versão do adaptador na publicação é 2.6.1.

Como Conectar o Agente Pi ao Servidor MCP Scrapeless

Pré-requisitos

• Node.js 18 ou mais recente. O Agente Pi e o pi-mcp-adapter ambos requerem; a variante do Gemini CLI do suporte ao Pi precisa do Node 20 ou mais recente.
• Uma conta Scrapeless e chave de API. Cadastre-se em app.scrapeless.com. Novas contas incluem tempo de execução gratuito do Navegador de Raspagem.
• Uma chave de API de um provedor de modelo que o Pi suporta — Anthropic, OpenAI, Google Gemini, Mistral, DeepSeek, Groq, ou qualquer um dos outros que o Pi lista em /login.

Etapa 1 — Instalar o Agente Pi

Abra seu terminal e execute:

npm install -g @mariozechner/pi-coding-agent

Verifique a instalação:

pi --version

O binário do Pi na publicação é @mariozechner/pi-coding-agent versão 0.73.1.

Etapa 2 — Instalar pi-mcp-adapter

Com o Pi instalado, adicione a extensão do adaptador MCP:

pi install npm:pi-mcp-adapter

Reinicie o Pi após a instalação. O adaptador puxa uma única ferramenta de proxy mcp que custa cerca de 200 tokens, além do comando de barra /mcp para gerenciamento interativo do servidor.

Passo 3 — Obtenha sua chave de API Scrapeless

Faça login em app.scrapeless.com, abra Configurações → Chaves de API e copie sua chave. Mantenha-a na área de transferência para o próximo passo.

Passo 4 — Configure o .mcp.json

Na sua pasta de projeto, crie um arquivo chamado .mcp.json. Este é o formato padrão do arquivo de configuração MCP que o pi-mcp-adapter lê na inicialização (nenhuma sintaxe específica do Pi é necessária):

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": {
        "SCRAPELESS_KEY": "SUA_CHAVE_SCRAPELESS"
      }
    }
  }
}

Substitua SUA_CHAVE_SCRAPELESS pela chave do Passo 3. O servidor MCP lê a chave da API a partir da variável de ambiente SCRAPELESS_KEY — esse nome é a fonte da verdade; não a altere para SCRAPELESS_API_KEY.

Na primeira execução, npx -y scrapeless-mcp-server baixa o pacote e inicia o servidor pela stdio. Nenhum comando de instalação separado é necessário.

Se preferir pular a stdio e usar o transporte HTTP streamable, troque a entrada para:

{
  "mcpServers": {
    "scrapeless": {
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "SUA_CHAVE_SCRAPELESS"
      }
    }
  }
}

Ambas as formas usam a mesma chave da API Scrapeless e disponibilizam as mesmas 21 ferramentas. A stdio é o padrão certo para uma estação de trabalho; o HTTP é o padrão certo se o Pi estiver rodando em um host em nuvem que não pode se conectar ao npx.

Passo 5 — Conecte-se a um provedor de modelo

Inicie o Pi:

pi

Você deve ver o pi-mcp-adapter listado em Extensões. Digite /login e escolha seu método de autenticação (assinatura ou chave da API). Escolha o provedor que deseja usar, cole a chave da API, e o Pi salvará a credencial para sessões futuras. Digite /model para abrir o painel de seleção de modelo e escolha um modelo.

Obtenha sua chave de API Scrapeless no plano gratuito: app.scrapeless.com

Passo 6 — Verifique a conexão

Digite /mcp para abrir o painel do MCP. O servidor scrapeless está listado, mas inativo — a princípio, pode mostrar 0/21 porque a conexão ainda não foi aberta. Destaque a linha com as teclas de seta e pressione Ctrl+R para reconectar (ou chame qualquer ferramenta Scrapeless, o que ativa uma conexão preguiçosa).

Uma vez conectado, a parte inferior do terminal mostra MCP: 1/1 servidores. As 21 ferramentas agora são descobertas. Para confirmar listando-as:

mcp({ search: "scrapeless" })

Você deve ver as ferramentas google_search, google_trends, browser_*, e scrape_* no resultado. Pressione Esc para fechar o painel.

Passo 7 — Execute uma tarefa real

Dê ao Pi um prompt que precisa de dados da web ao vivo. Por exemplo:

Pesquise na web pela documentação oficial do npm axios, extraia a página mais relevante,
e gere um exemplo de JavaScript funcional que faça uma requisição GET com o devido tratamento
de erros. Salve-o como axios-example.js.

O Pi chama scrapeless_google_search primeiro, retornando uma lista classificada de resultados com títulos, URLs e trechos da documentação oficial do axios. Ele então escolhe a URL mais relevante e chama scrapeless_scrape_markdown para puxar a página como Markdown limpo — o navegador em nuvem lida com a renderização do JavaScript e quaisquer desafios de anti-detecção ao longo do caminho, e o Pi recebe o conteúdo extraído em vez do HTML bruto.

Com a documentação em contexto, o Pi gera axios-example.js contra a versão da API que acabou de ler. Se um erro transitório os error 10054 ou HTTP 503 surgir, tente novamente a chamada — a frota do navegador em nuvem recicla sessões e uma nova tentativa normalmente tem sucesso.

Passo 8 — Explore a saída

O Pi escreve axios-example.js na sua pasta de projeto. O arquivo contém um exemplo que reflete os padrões que acabou de extrair — async/await, ramificação de código de status e inspeção de erros consistentes com o que a documentação atual do axios recomenda:

async function fetchPost() {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/posts/1');
    console.log('Status:', response.status);
    console.log('Título:', response.data.title);
    console.log('Corpo:', response.data.body);
  } catch (error) {
    if (error.response) {
      console.error('Status:', error.response.status);
      console.error('Dados:', error.response.data);
    } else if (error.request) {
      console.error('Nenhuma resposta recebida do servidor');
    } else {
      console.error('Erro na configuração da requisição:', error.message);
    }
  }
}

Execute-o:

npm install axios
node axios-example.js

O que você recebe de volta

Uma resposta representativa de tools/list do servidor Scrapeless MCP tem esta estrutura (o esquema reflete o servidor ao vivo na publicação; os valores dos campos são amostras ilustrativas):

{
  "tools": [
    {
      "name": "google_search",
      "description": "Mecanismo de busca de informações universal",
      "inputSchema": {
        "type": "object",
        "properties": {
          "q":  { "type": "string", "default": "Principais manchetes de notícias" },
          "gl": { "type": "string", "default": "us" },
          "hl": { "type": "string", "default": "en" }
        }
      }
    },
    {
      "name": "scrape_markdown",
      "description": "Raspar um URL e retornar seu conteúdo como Markdown",
      "inputSchema": {
        "type": "object",
        "properties": { "url": { "type": "string", "format": "uri" } },
        "required": ["url"]
      }
    },
    { "name": "browser_create",   "description": "Criar uma nova sessão de navegador na nuvem" },
    { "name": "browser_goto",     "description": "Navegar para um URL em uma sessão existente" },
    { "name": "browser_get_html", "description": "Retornar o HTML renderizado da página ativa" }
    // …16 mais
  ]
}

Observações honestas após conectar tudo isso:

• O custo do token é dominado pela ferramenta proxy, não pelas 21 ferramentas subjacentes. O adaptador mantém metadados em um cache de disco; nada é carregado no prompt do sistema até que você chame directTools em um servidor.
• O início preguiçoso é vantajoso em sessões frias. O servidor Scrapeless MCP só é ativado na primeira vez que Pi chama uma de suas ferramentas, então abrir uma sessão Pi que tenha o servidor configurado não custa nada extra.
• google_search + scrape_markdown é o par comum. Pesquise para encontrar a página, raspe para lê-la. As ferramentas browser_* são reservadas para fluxos que precisam de login, cliques ou paginação.
• O erro transitório os error 10054 / HTTP 503 acontece. Está documentado nos guias Scrapeless e surge na troca de sessões de navegador na nuvem. Tente novamente a chamada da ferramenta a partir do Pi em vez de reiniciar a sessão.
• SCRAPELESS_KEY é a variável de ambiente canônica. Outras superfícies Scrapeless (o CLI independente, a habilidade do agente) usam SCRAPELESS_API_KEY. O servidor MCP é a exceção.

Conclusão: um agente de codificação mínimo que lê a web ao vivo

O Pi Agent permanece mínimo por padrão; o Servidor Scrapeless MCP adiciona 21 ferramentas web sem mudar isso. O tecido conectivo é pi-mcp-adapter — uma ferramenta proxy, ~200 tokens, início lazar do servidor — e um arquivo .mcp.json que o ecossistema MCP mais amplo já entende. O mesmo trecho JSON pode ser utilizado em Claude Desktop, Cursor, Codex CLI, Gemini CLI, Windsurf ou VS Code Copilot Chat sem alterações.

A diferença qualitativa aparece na primeira vez que você pede ao Pi para gerar código contra uma biblioteca que você não definiu: em vez de adivinhar a partir da memória dos dados de treinamento, o Pi pesquisa, raspa a documentação canônica e escreve seu exemplo contra a versão que está realmente ao vivo. Combine este guia com a visão geral do Servidor Scrapeless MCP para o catálogo completo de ferramentas, ou com o guia AWS Strands + Scrapeless MCP se o mesmo servidor MCP estiver sendo integrado a um agente baseado em framework, em vez de um terminal. Mantenha o modo apenas proxy para uso normal, promova ferramentas individuais para directTools quando você quiser que o modelo as veja em seu prompt de sistema e mantenha lifecycle: lazy para que sessões frias permaneçam baratas.

Pronto para Construir Seu Pipeline de Dados Potencializado por IA?

Junte-se à nossa comunidade para reivindicar um plano gratuito e conectar-se com desenvolvedores construindo pipelines de agentes impulsionados por MCP: Discord · Telegram.

Inscreva-se em app.scrapeless.com para um tempo de execução gratuito do Scraping Browser, em seguida, insira o trecho .mcp.json acima no Pi (ou qualquer outro cliente MCP) e comece a fundamentar a geração de código em dados da web ao vivo. Detalhes de preços em scrapeless.com/en/pricing.

FAQ

1. É legal raspar com o servidor Scrapeless MCP através do Pi?
O servidor MCP apenas acessa conteúdo publicamente disponível, o mesmo conteúdo que um usuário desconectado veria em um navegador. A legalidade depende da jurisdição e dos Termos de Serviço do site alvo. Revise os ToS de qualquer site que o Pi seja solicitado a raspar e consulte um advogado para casos de uso de alto risco.

2. Preciso de um proxy além do servidor Scrapeless MCP?
Não. O navegador na nuvem já se conecta através de proxies residenciais em mais de 195 países. Use o parâmetro gl na google_search (ou uma dica de estilo --proxy-country no prompt do agente) para especificar uma região.

3. O que o Pi vê se uma chamada de ferramenta tiver ERR_TUNNEL_CONNECTION_FAILED, os error 10054 ou HTTP 503?
Esses são erros transitórios na frota do navegador em nuvem. O Pi reporta o erro ao modelo, que normalmente tenta novamente automaticamente; se não, reenvie o prompt. Eles não são um sinal de que a fiação do MCP está quebrada.

4. O Pi mostra o servidor Scrapeless, mas 0/21 ferramentas — o que está errado?
Nada. Servidores são preguiçosos por padrão no pi-mcp-adapter. A contagem muda para 21/21 na primeira vez que o Pi chama uma ferramenta Scrapeless. Para forçar a conexão, destaque o servidor em /mcp e pressione Ctrl+R, ou execute /mcp reconnect scrapeless na linha de prompt.

5. A ferramenta proxy é excelente, mas posso expor ferramentas Scrapeless diretamente para o modelo do Pi?
Sim — adicione "directTools": true (ou "directTools": ["google_search", "scrape_markdown"] para promover um subconjunto) à entrada scrapeless no .mcp.json. Ferramentas diretas custam cerca de 150–300 tokens cada no prompt do sistema; escolha as que o agente usa com mais frequência.

6. O mesmo trecho de .mcp.json pode ser usado fora do Pi?
Sim. O objeto mcpServers é o envelope de configuração MCP padrão. Claude Desktop, Cursor, Codex CLI, Gemini CLI, Windsurf e VS Code Copilot Chat todos o leem (alguns com pequenas diferenças de caminho ou nome de arquivo). O bloco Scrapeless acima funciona em todos eles.

7. Quantos servidores MCP o Pi pode conectar ao mesmo tempo?
Não há um limite rígido — o pi-mcp-adapter mantém cada servidor preguiçoso e desconecta após 10 minutos ociosos, então o custo de tokens e processos permanece constante, independentemente de quantos servidores estão listados. O teto relevante é a janela de contexto do provedor do modelo e o próprio orçamento por ferramenta do Pi.

8. Isso funciona sem um agente de IA — posso chamar o servidor MCP Scrapeless a partir de um script?
Sim. O ponto de extremidade HTTP streamable em https://api.scrapeless.com/mcp pode ser chamado de qualquer cliente HTTP com a sequência JSON-RPC initialize → tools/list → tools/call; um teste de fumaça curl contra ele retorna serverInfo.name: "scrapeless-mcp-server" e um cabeçalho mcp-session-id para chamadas de acompanhamento. O Pi é a camada de conveniência, não uma dependência rígida.