Painel
PT
Comece grátis

Busca na web no Claude Code, no Cursor e no Codex com um único servidor MCP

Um servidor MCP remoto dá a um agente de programação 15 ferramentas: busca na web, páginas em markdown, mapas, Amazon, transcrições do YouTube. Setup para três clientes, testado.

Um agente de programação que não consegue ler a web chuta versões de biblioteca e inventa flags de API. A solução não é uma ferramenta customizada por projeto: é um servidor MCP remoto, adicionado uma vez em cada cliente, que o agente pode chamar para buscar e para ler páginas.

O FastAF roda um em https://api.fastaf.co/mcp (Streamable HTTP, stateless, spec 2026-07-28), autenticado com a mesma chave Bearer da API REST. Abaixo está o setup para três clientes, o protocolo cru e quanto custa uma sessão. Todas as chamadas foram feitas em 19 de outubro de 2026.

O que o agente recebe do servidor?

tools/list devolve 15 ferramentas: scrape_page, search_web, search_places, search_amazon, search_news, search_shopping, get_trends, search_scholar, search_jobs, ask_google_ai, search_walmart, search_x, search_youtube, youtube_transcript, get_linkedin_profile. Cada uma é marcada como readOnlyHint: true e tem um input schema estrito, com descrição em todos os parâmetros, então o modelo sabe o que pode passar.

Os custos são os mesmos da REST: search_web custa 5 créditos, scrape_page custa 1 (5 com render_js: true), search_amazon e youtube_transcript custam 1, get_linkedin_profile custa 60. A lista completa está nas páginas das APIs e na documentação do MCP.

Antes de tudo, coloque a chave numa variável de ambiente, para que ela nunca vá parar num arquivo de configuração que você possa commitar:

export FASTAF_API_KEY="..."   # em ~/.zshrc ou ~/.bashrc

Como adicionar ao Claude Code?

Segundo a documentação de MCP do Claude Code (code.claude.com/docs/en/mcp, verificada em 19 de outubro de 2026), servidores remotos usam --transport http e um header:

claude mcp add --transport http fastaf https://api.fastaf.co/mcp \
  --header "Authorization: Bearer $FASTAF_API_KEY"

O seu shell expande a variável, então a chave acaba gravada em ~/.claude.json. Para compartilhar o servidor com um time, use um .mcp.json de projeto: o Claude Code expande ${VAR} dentro de headers, então o arquivo não contém nenhum segredo.

{
  "mcpServers": {
    "fastaf": {
      "type": "http",
      "url": "https://api.fastaf.co/mcp",
      "headers": { "Authorization": "Bearer ${FASTAF_API_KEY}" }
    }
  }
}

claude mcp list mostra se a conexão deu certo. Rodamos exatamente esse arquivo com o Claude Code 2.1.197 em modo headless; o modelo recebeu o JSON da ferramenta (text, truncated, total_chars, credits_used, credits_remaining).

Como adicionar ao Cursor?

A documentação do Cursor (cursor.com/docs/context/mcp, verificada em 19 de outubro de 2026) lê ~/.cursor/mcp.json globalmente ou .cursor/mcp.json por projeto, e resolve ${env:NAME} em url e headers:

{
  "mcpServers": {
    "fastaf": {
      "url": "https://api.fastaf.co/mcp",
      "headers": { "Authorization": "Bearer ${env:FASTAF_API_KEY}" }
    }
  }
}

Não rodamos o Cursor para este post; a configuração segue a documentação dele.

Como adicionar ao Codex CLI?

A documentação de MCP do Codex (developers.openai.com/codex/mcp, verificada em 19 de outubro de 2026) usa bearer_token_env_var, que indica o nome da variável em vez de guardar o token. Em ~/.codex/config.toml:

[mcp_servers.fastaf]
url = "https://api.fastaf.co/mcp"
bearer_token_env_var = "FASTAF_API_KEY"

Ou codex mcp add fastaf --url https://api.fastaf.co/mcp --bearer-token-env-var FASTAF_API_KEY (flag presente no codex-cli 0.159.2). codex mcp list, ou /mcp na TUI, mostra o servidor. Uma execução de codex exec com essa configuração chamou search_web e devolveu três resultados por 5 créditos.

Como é uma chamada MCP crua?

A spec 2026-07-28 é stateless: não existe handshake, e initialize devolve -32601 Method not found. Cada requisição carrega a versão num header e em _meta, mais um header Mcp-Method (sem ele o servidor responde -32020, headers e body não batem):

curl -s https://api.fastaf.co/mcp \
  -H "Authorization: Bearer $FASTAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" -H "Mcp-Name: search_web" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
       "name":"search_web","arguments":{"query":"python 3.14 free-threaded","results":3},
       "_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28",
                "io.modelcontextprotocol/clientCapabilities":{}}}}'

Saída real, resumida:

{"results":[
  {"title":"Python support for free threading ...",
   "url":"https://docs.python.org/3/howto/free-threading-python.html","position":1},
  {"title":"Python Free-Threading Guide","url":"https://py-free-threading.github.io/","position":3}],
 "credits_used":5,"credits_remaining":937}

A mesma chamada com scrape_page nessa URL e max_chars: 4000 devolveu "truncated":true,"total_chars":20229,"credits_used":1.

Por que markdown com limite e não HTML cru?

O contexto é o orçamento de verdade. A página “What’s new” do Python 3.14 tem 554.786 bytes de HTML quando baixada com curl. O scrape_page transformou isso em 266.828 caracteres de markdown e devolveu os primeiros 12.000 (o max_chars padrão, ajustável de 1.000 a 30.000), em 1,3 segundo por 1 crédito. O guia de free-threading, menor, foi de 41.838 bytes de HTML para 20.229 caracteres.

A cerca de quatro caracteres por token, 12.000 caracteres são uns 3.000 tokens. A documentação do Claude Code diz que ele avisa acima de 10.000 tokens de saída de ferramenta e corta em 25.000 por padrão, então o HTML cru seria cortado ou salvo num arquivo antes de o modelo ver qualquer coisa útil. truncated e total_chars avisam o agente de que há mais, para que ele possa pedir de novo com um limite maior.

Os resultados de busca são compactos do mesmo jeito: título, url, snippet e posição, nada além disso.

Quanto custa uma sessão de programação?

Uma sessão de pesquisa pesada, com 10 buscas e 10 leituras de página, custa 10 x 5 + 10 x 1 = 60 créditos. Os 500 créditos grátis cobrem oito dessas; o pacote Starter de US$ 10 (20.000 créditos) cobre 333, cerca de 3 centavos cada. Veja os preços.

O teto rígido é o saldo da conta. Todo resultado informa credits_remaining, e quando ele chega a zero as ferramentas param de cobrar e devolvem um erro. Use uma chave por máquina, para poder revogar sozinha a chave de um laptop perdido, mas o saldo é compartilhado por todas as chaves da conta: não existe orçamento por chave. O post sobre teto de gastos trata dos limites por execução.

O que dá errado e como resolver?

  • HTTP 401, -32001 Authentication required: o header está faltando ou a variável está vazia no ambiente do cliente. Apps com interface gráfica muitas vezes não leem o perfil do seu shell.
  • Sem créditos (402 na REST): a ferramenta devolve INSUFFICIENT_CREDITS com credits_used: 0. Recarregue; nada foi cobrado.
  • Chamadas demais ao mesmo tempo (429 na REST): os resultados voltam como RATE_LIMITED quando o agente dispara mais chamadas em paralelo do que a concorrência do seu pacote (1 no Free, 5 no Starter). A nossa execução do Codex bateu nisso duas vezes antes de dar certo. Uma rajada no próprio endpoint devolve HTTP 429 com Retry-After: 10.

Resumindo

Exporte FASTAF_API_KEY, adicione https://api.fastaf.co/mcp com um header Bearer no Claude Code, no Cursor ou no Codex, e o agente ganha busca, leitura de páginas em markdown com limite e mais 13 ferramentas, com o saldo como teto. Pegue uma chave com 500 créditos grátis.