ContextFetch

API de busca web e servidor MCP para agentes de IA: resultados como Markdown limpo com contexto podado por consulta, além de pesquisa, rastreamento e mapa. US$ 1 por 1.000 buscas; 25 por dia grátis sem chave.

GitHub

Servidor MCP hospedado

npx add-mcp 'https://api.contextfetch.dev/mcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

@contextfetch/mcp

Servidor MCP para ContextFetch: busca neural na web e Markdown limpo e pronto para LLM para agentes de IA a partir de US$ 0,75 por 1.000 buscas. Funciona sem cadastro: nenhuma chave necessária para o nível gratuito.

Instalação

Claude Code (uma linha, sem chave):

claude mcp add contextfetch -- npx -y @contextfetch/mcp

Com uma chave paga:

claude mcp add contextfetch -e CONTEXTFETCH_API_KEY=your_key -- npx -y @contextfetch/mcp

Cursor: adicione em ~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto):

{
  "mcpServers": {
    "contextfetch": {
      "command": "npx",
      "args": ["-y", "@contextfetch/mcp"],
      "env": { "CONTEXTFETCH_API_KEY": "your_key" }
    }
  }
}

Windsurf: adicione em ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "contextfetch": {
      "command": "npx",
      "args": ["-y", "@contextfetch/mcp"],
      "env": { "CONTEXTFETCH_API_KEY": "your_key" }
    }
  }
}

Para usar o nível gratuito, remova o bloco env (ou deixe CONTEXTFETCH_API_KEY vazio). O mesmo JSON funciona no claude_desktop_config.json do Claude Desktop e em qualquer outro cliente MCP que execute servidores stdio.

Requer Node.js 18 ou superior.

Ferramentas

Ferramenta	Argumentos	O que faz	Custo
`contextfetch_search`	`query`, `num_results` (1-25, padrão 5), `include_domains?`, `exclude_domains?`	Busca na web. Cada resultado retorna título, URL e apenas as passagens relevantes à sua consulta (Markdown podado por cross-encoder).	1 crédito
`contextfetch_extract_url`	`url`, `query?`	Qualquer página pública (documentação, artigos, arquivos do GitHub, arXiv) como Markdown limpo com tabelas preservadas. Com `query`, retorna apenas as passagens relevantes.	1 crédito
`contextfetch_find_similar`	`url`, `num_results` (1-25, padrão 5)	Páginas semelhantes a uma URL, excluindo o próprio domínio.	1 crédito
`contextfetch_research`	`query`, `sub_queries?` (até 5), `num_results_per_query` (1-10, padrão 5)	Pesquisa no servidor: executa as subconsultas em paralelo, remove duplicatas de páginas por URL, classifica todas contra `query` com o cross-encoder e retorna um pacote de evidências em Markdown (fontes numeradas `[n]` com suas passagens podadas pela consulta, citadas textualmente; nada é gerado), encabeçado pelas subconsultas, contagem de fontes, tokens e créditos usados.	1 crédito por subconsulta (máx. 5)
`contextfetch_deep_research`	`query`, `sub_queries?` (até 3), `num_results_per_query` (1-25, padrão 5; no máximo 10 usados)	O nome anterior de `contextfetch_research`, mantido para configurações existentes: mesmo pacote de evidências no servidor, até 3 subconsultas.	1 crédito por subconsulta (máx. 3)
`contextfetch_answer`	`query`, `num_results` (1-10, padrão 5)	Resposta extrativa: as passagens com melhor pontuação das principais páginas, citadas textualmente com marcadores `[n]` e uma lista numerada de fontes. Nenhum texto é gerado, então é mais adequado para consultas factuais do que perguntas abertas.	1 crédito
`contextfetch_crawl`	`url`, `max_depth` (0-3, padrão 1), `limit` (1-50, padrão 10), `query?`, `include_paths?`, `exclude_paths?` (regex no caminho da URL)	Rastreia um site a partir de `url` (links do mesmo site, robots.txt respeitado) e retorna cada página como Markdown com sua profundidade. Com `query`, as páginas são classificadas por relevância e podadas para as passagens relevantes.	1 crédito por página retornada
`contextfetch_map`	`url`, `limit` (1-5.000, padrão 100), `include_paths?`, `exclude_paths?`	Lista as URLs de um site a partir de seus sitemaps e dos links da página inicial sem buscar as páginas.	1 crédito
`contextfetch_balance`	nenhum	Créditos restantes, taxa de consumo (créditos/dia nos últimos 7 dias) e configurações de recarga automática, incluindo o último erro de recarga automática se um pagamento falhou. Requer `CONTEXTFETCH_API_KEY`.	gratuito
`contextfetch_get_free_key`	nenhum	Reivindica a chave de API gratuita da rede (2.500 buscas, uma por rede) e a usa pelo restante da sessão. Entregue ao seu usuário para guardar em `CONTEXTFETCH_API_KEY`.	gratuito
`contextfetch_auto_reload`	`enabled`, `threshold?` (100-100.000), `pack?` (`instant`, `builder`, `scale`), `monthly_max_usd?` (máx. 500)	Ativa ou desativa a recarga automática ou a altera: quando os créditos caírem abaixo de `threshold`, o cartão salvo no checkout compra `pack` novamente, até o limite mensal. Requer `CONTEXTFETCH_API_KEY` e um cartão salvo. O limite não pode exceder US$ 500 aqui.	gratuito

Todas as ferramentas retornam texto em Markdown. Sem chave, contextfetch_balance e contextfetch_auto_reload retornam uma mensagem curta informando que precisam de uma, com o link de compra. No nível gratuito, os resultados começam com um aviso de uma linha mostrando quantas buscas gratuitas restam hoje. Quando a API os reporta, uma linha final mostra a latência (total e por etapa: recall, fetch, rerank), se a resposta veio do cache e a economia de tokens (tokens podados vs. tokens brutos da página).

Subconsultas de `contextfetch_research`

Passe suas próprias sub_queries (diferentes ângulos sobre a pergunta); a descrição da ferramenta instrui o modelo chamador a fazer isso. Se você as omitir, a API as deriva de query com regras fixas:

a própria consulta;
a consulta + documentation;
a consulta + benchmark quando menciona velocidade, desempenho, latência, memória ou uma comparação (vs, compare), caso contrário a consulta + example.

Um sufixo que a consulta já contém é ignorado (então react useActionState example executa 2 buscas, não 3). Toda a pesquisa é executada no servidor em uma única chamada /v1/research que custa 1 crédito por subconsulta; uma subconsulta que falha é reembolsada e nomeada no cabeçalho. Se todas falharem, a ferramenta retorna o erro.

Variáveis de ambiente

Variável	Padrão	Significado
`CONTEXTFETCH_API_KEY`	não definida	Sua chave de API. Não definida ou vazia usa o nível gratuito sem chave.
`CONTEXTFETCH_API_BASE`	`https://api.contextfetch.dev`	URL base da API. Aponte para seu próprio mecanismo se você fizer self-hosting.

Nível gratuito e preços

Pacote	Preço	Créditos	Por 1.000
Teste sem chave	US$ 0	25 por dia por IP	gratuito, sem cadastro
Instantâneo	US$ 15	15.000	US$ 1,00
Construtor (mais popular)	US$ 50	60.000	US$ 0,83
Escala	US$ 150	200.000	US$ 0,75

Pagamentos únicos; os créditos nunca expiram. A recarga automática opcional recompra um pacote quando seu saldo cai abaixo de um limite, até um teto mensal.

Quando os créditos ou o nível gratuito acabam (HTTP 402), a ferramenta retorna os pacotes com preços e um link de compra com um clique para cada um (pacote recomendado primeiro), além de uma linha para repassar ao seu usuário. Os links de compra vão direto para o Stripe Checkout (cartão, Apple Pay, Google Pay): https://api.contextfetch.dev/buy/instant, /buy/builder, /buy/scale. Em seguida, defina CONTEXTFETCH_API_KEY como mostrado acima.

Tentativas e conexões

Falhas de conexão antes do envio da solicitação (recusada, DNS, tempo limite de conexão), HTTP 429 e HTTP 5xx são repetidas com backoff exponencial e jitter (cerca de 0,25-0,5 s, depois 0,5-1 s), no máximo 3 tentativas por chamada de API e 30 segundos no total, tentativas incluídas. Um 429 ou 5xx com um cabeçalho Retry-After espera exatamente esse tempo, a menos que isso ultrapasse o orçamento de 30 segundos. 400, 401, 402, 422 e outras respostas 4xx nunca são repetidas. Uma conexão que cai após o envio da solicitação também não é repetida, pois a busca pode já ter sido cobrada. As conexões são agrupadas e mantidas ativas pelo fetch integrado do Node (undici), portanto não há dependência HTTP extra.

Erros

Erros nunca derrubam o servidor; eles retornam como resultados de ferramenta com isError: true e uma explicação simples: chave inválida (401), sem créditos ou limite gratuito atingido (402, lista os pacotes com seus links de compra), sem cartão salvo para recarga automática (409, com o link de compra), URL não permitida (400, apenas URLs http(s) públicas), uma página que contextfetch_extract_url não conseguiu buscar (com o motivo, como HTTP 404), limite de taxa (429), erros de servidor (5xx), falhas de rede e um limite de 30 segundos por chamada (tentativas incluídas).

Desenvolvimento

npm install
npm run build          # compiles src/ to dist/ and marks dist/index.js executable
npm test               # builds, then drives dist/index.js over stdio against a local mock API (no network)
CONTEXTFETCH_API_BASE=http://localhost:8000 node dist/index.js

Publicação

Publicar @contextfetch/mcp requer a organização npm contextfetch (crie-a em npmjs.com e adicione a conta de publicação como membro). Depois, execute npm publish a partir desta pasta; publishConfig.access já está public e prepublishOnly compila primeiro.

Licença

MIT