Servidor MCP

Servidor MCP

Use o FourA a partir de qualquer cliente Model Context Protocol (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) como quatro ferramentas nativas e seis prompts de fluxo de trabalho. Sem código de integração, sem cliente HTTP personalizado.

Código aberto no GitHub; no npm como @fouradata/mcp. Versão atual: 0.8.3.

Obtenha uma chave em foura.ai/dashboard#api-keys (um clique, formato pk_live_..., e Reveal exibe a chave novamente mais tarde). Adicione isto à configuração do seu cliente MCP:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": { "FOURA_API_KEY": "pk_live_..." }
    }
  }
}

Atenção com o Claude Desktop: feche totalmente o Claude Desktop (Cmd+Q no macOS) antes de editar o arquivo de configuração. Se o aplicativo ainda estiver em execução, ele sobrescreverá suas alterações com a configuração em memória ao encerrar.

O comando npx baixa o @fouradata/mcp na primeira inicialização e o executa como um subprocesso do seu cliente MCP. Nenhuma instalação global é necessária.

Cliente Onde fica a configuração
Claude Desktop (macOS) ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows) %APPDATA%\Claude\claude_desktop_config.json
Claude Code claude mcp add foura -- npx -y @fouradata/mcp (defina FOURA_API_KEY no ambiente primeiro)
Cursor ~/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
VS Code (extensão MCP) .vscode/mcp.json, sob uma chave servers de nível superior em vez de mcpServers

Reinicie o cliente. As ferramentas (foura_auto, foura_single, foura_proxy, foura_browser) e seis prompts aparecerão na sua lista de ferramentas.

Início rápido: hospedado (Streamable HTTP)

Para clientes que suportam o transporte Streamable HTTP (Cursor, Windsurf, VS Code, Claude Code com --transport http), aponte-os para o endpoint hospedado em vez de executar um subprocesso local:

{
  "mcpServers": {
    "foura": {
      "url": "https://mcp.foura.ai/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}

Para o Claude Desktop, use a configuração stdio acima ou faça o bridge do endpoint hospedado por meio do mcp-remote:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
    }
  }
}

Referência do endpoint hospedado

Propriedade Valor
URL https://mcp.foura.ai/mcp
Transporte Streamable HTTP (POST /mcp, respostas SSE)
Autenticação Authorization: Bearer pk_live_... por request. Uma chave simples em Authorization, ou X-API-Key: pk_live_..., também funciona
MCP-Protocol-Version Conforme @modelcontextprotocol/sdk (atualmente 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)
Desafio 401 WWW-Authenticate: Bearer realm="foura-mcp"

O desafio 401 não inclui o parâmetro RFC 9728 resource_metadata, intencionalmente. Anunciar um parâmetro faz com que um cliente compatível com OAuth inicie um fluxo que este servidor não implementa. Envie sua chave pk_live_ como um Bearer token e o erro 401 desaparecerá.

O servidor hospedado é stateless. Cada request traz sua própria chave, que o servidor encaminha para a API do FourA como X-API-Key. Uma única chave libera todas as quatro ferramentas.

Para proteção contra DNS-rebinding (CVE-2025-66414), o servidor valida o header Host (deve ser mcp.foura.ai ou localhost) e o header Origin quando presente (na lista de permissões: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Chamadores server-to-server (curl, clientes MCP em modo de ponte stdio) não enviam Origin e passam direto.

Ferramentas

Todas as quatro ferramentas são anotadas com readOnlyHint: true e openWorldHint: true de acordo com a especificação MCP 2025-06-18. Clientes que aprovam automaticamente ferramentas confiáveis somente leitura as chamam sem um modal de confirmação por request.

foura_auto é o padrão inteligente: forneça uma URL e ele retornará o conteúdo, escolhendo o método de fetch para você. As outras três são as primitivas de nível inferior que ele orquestra; utilize-as quando quiser controle explícito.

foura_auto

Forneça uma URL quando quiser que o FourA escolha o método de request. Ele realiza tentativas limitadas entre os caminhos disponíveis de HTTP, proxy e navegador. Passe validate em alvos protegidos para que a resposta contenha conteúdo que identifique a página real. Se nenhuma tentativa atender à validação, a ferramenta retornará um erro em vez de apresentar uma página de desafio como sucesso.

A resposta inclui detalhes da conclusão em meta e, por padrão, uma session reutilizável com proxy, cookies e userAgent. Para um acompanhamento simples, chame foura_single com session.proxy como proxy, serialize os cookies como um header Cookie e envie session.userAgent como o header User-Agent. Para renderização de JavaScript, passe os valores da sessão para os campos correspondentes de foura_browser.

Defina exitClass: "premium" para permitir que o Auto escale para uma saída premium quando o pool padrão não conseguir alcançar a página. exitClass: "standard" e omitir o campo mantêm o Auto no pool padrão, e apenas uma request que especifica uma classe recebe exitClass de volta. Funciona como em foura_proxy: uma permissão, não uma instrução, contabilizada contra o tráfego premium do seu plano, e recusada com code: "plan_limit_premium" em um plano sem saídas premium. O exitClass do resultado informa qual classe fez a entrega. Consulte exitClass no Smart Fetch.

foura_single

Uma request HTTP, resposta de volta. Espelha POST /api/single/ de forma direta.

Use para páginas estáticas, APIs JSON e HTML renderizado no servidor.

Escolhendo qual navegador você apresenta

Uma request apresenta o Google Chrome mais recente por padrão. Quando um destino aceita um navegador e recusa outro, defina browser (Chrome, Edge, Safari, Firefox ou Tor), os (Windows, macOS, Android ou iOS) ou version, ou passe um id profile exato:

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

A versão mais recente prevalece quando vários perfis correspondem. Uma combinação inexistente retorna um erro listando o que está disponível, garantindo que uma request nunca seja enviada como um navegador que você não escolheu. A seleção requer unblocker, que fica ativado por padrão. O catálogo é publicado em GET /api/profiles e não requer API key.

Os mesmos quatro campos estão presentes no objeto request de foura_proxy.

foura_proxy

Encaminhe uma HTTP request por meio de proxies rotativos com retry automático. Use-o quando foura_single estiver bloqueado ou o destino exigir um país de saída específico.

Defina exitCountries com uma allowlist estrita de códigos de país de duas letras visíveis ao destino, fornecidos pelo usuário ou pelas exigências do destino:

{
  "maxTries": 5,
  "exitCountries": ["CZ", "GB"],
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "browser": "Chrome",
    "os": "Windows"
  }
}

Os valores são normalizados (trimmed), convertidos para maiúsculas e deduplicados. Saídas do pool padrão com país desconhecido são excluídas, e o pool padrão nunca faz fallback para um país não solicitado. Uma saída premium também permanece dentro da lista: com exitClass: "premium", o pool padrão ainda vai primeiro, e uma saída premium parte de um dos seus países e o nomeia em exitCountry. A seleção usa os metadados de país visíveis ao destino mais recentes disponíveis, normalmente atualizados em até dez minutos; não é uma consulta de geolocalização em tempo real durante a requisição. Não deduza o país de atendimento a partir do endereço de host do proxy.

Um sucesso com escopo definido retorna exitCountry e o ID reutilizável proxy. Verifique se exitCountry pertence à lista de permissões solicitada. Se o pool atual não tiver correspondência, a ferramenta retorna code: "no_eligible_proxy" com o escopo normalizado em details.exitCountries. Preserve esse escopo e tente novamente mais tarde. Altere ou amplie apenas quando o usuário alterar explicitamente o requisito. O escopo por país está incluído a partir do plano Startup. Em um plano sem esse recurso, uma chamada que envia exitCountries é recusada com 403 e X-FourA-Limit: plan_limit_feature.

Se a página selecionada precisar de JavaScript posteriormente, passe o ID proxy retornado para foura_browser.proxy para que o navegador reutilize a mesma saída.

Defina exitClass: "premium" para um destino que o pool padrão não consegue alcançar, independentemente de quantas saídas sejam tentadas. É uma permissão, não uma instrução: o pool padrão ainda disputa pela resposta e geralmente vence, e uma requisição respondida por ele antes de qualquer saída premium ser tentada não consome tráfego premium. Uma tentativa premium contabiliza o tráfego transportado mesmo quando falha. A resposta relata exitClass de volta, premium ou standard, para que você possa ver por requisição qual classe atendeu você. standard também é a resposta quando o tráfego premium incluído no seu plano acaba, sendo um resultado normal e não um erro. exitClass: "standard" proíbe o escalonamento diretamente. exitClass: "premium" em um plano sem saídas premium é recusado com code: "plan_limit_premium". Consulte exitClass.

Quando a rotação precisa mudar para outro navegador para obter uma resposta, uma resposta bem-sucedida traz profile: o id de perfil do catálogo no qual ela se fixou. Passe-o como profile na próxima chamada para apresentar o mesmo navegador.

Uma rotação com falha traz attemptReport ao lado do erro: uma frase em summary, além de contagens que separam saídas que nunca responderam (noResponse), saídas que uma verificação de bot recusou (defense, com os fornecedores em vendors), páginas que chegaram e foram rejeitadas apenas pelo seu próprio validate.data (contentRejected), statusRejected e other. profilesTried lista os navegadores enviados pela tarefa, em ordem de primeiro uso, com default significando que a requisição saiu exatamente como foi escrita. Um valor alto em contentRejected significa que o FourA entregou páginas reais e sua própria regra as descartou. Consulte Why a Proxy Request Ran Out of Tries.

foura_browser

Sessão completa de navegador. O JavaScript é executado, o DOM é renderizado e os cookies são retornados. Espelha POST /api/browser/.

Use para single-page apps, conteúdo carregado sob demanda (lazy-loaded) ou páginas com verificações que exigem um navegador real para serem concluídas.

Para os formatos de entrada, padrões e regras de validação de cada ferramenta, consulte a referência de endpoints REST. Os schemas das ferramentas correspondem à API REST, além do opt-in offload_large exclusivo para MCP (veja abaixo), com duas exceções: foura_browser não possui o campo lean, e foura_proxy ainda não possui campos de local de saída. Um valor enviado sob esses nomes nunca chega à API. Para definir um, chame POST /api/browser/ ou POST /api/proxy/ diretamente.

Quando o destino executa uma verificação de bot

foura_single e foura_proxy retornam defense quando o destino executou uma verificação de bot a caminho do body. defense.solved: true significa que a verificação foi atendida e data é a página real; false significa que o body pode ser uma página de desafio. Tente novamente com outro navegador, sistema operacional ou versão, ou avance para foura_proxy ou foura_browser, em vez de tratar a página de desafio como conteúdo.

Respostas tipadas

Toda resposta de ferramenta inclui tanto content (resumo em texto legível por humanos) quanto structuredContent (JSON tipado validado contra o outputSchema da ferramenta). Cada ferramenta possui sua própria estrutura única:

  • foura_auto: formato single { status, headers, data } mais meta ({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }, sempre presente, onde rung é um entre cache, probe, proxy, browser, warmup, fail) e, por padrão, session ({ proxy, cookies, userAgent }) para repetição pelas ferramentas de nível inferior; uma requisição que definiu uma classe também inclui exitClass. meta.attemptsByEngine conta as requisições que a chamada enviou para Single, Proxy e Browser, e meta.browserRequests conta aquelas que consumiram sua cota diária de Browser. Uma falha também inclui attemptReport. Sem total_time.
  • foura_single: { status, headers, data, total_time, ... } (headers é um array, uma entrada por salto de redirecionamento)
  • foura_proxy: igual a single mais { proxy, total }; um sucesso com escopo definido também inclui exitCountry, uma requisição que definiu uma classe inclui exitClass, uma rotação que alterou a família do navegador inclui profile, e uma falha inclui attemptReport
  • foura_browser: estrutura distinta { status, headers: object, body, cookies, userAgent } (observação: body pode ser uma string ou objeto dependendo do content-type)

Toda ferramenta também informa o custo da chamada e como rastreá-la, lidos dos headers de resposta da API:

  • credits - créditos gastos nesta chamada. Presente também em falhas, porque o trabalho foi realizado de qualquer forma. Você é cobrado apenas por chamadas bem-sucedidas, portanto, uma falha exibe seus créditos aqui, mas não custa nada a você.
  • request_id - ID da FourA para a chamada. Mencione-o em uma solicitação de suporte.
  • exitClass - premium quando uma saída premium atendeu à chamada. No foura_single e no foura_browser, isso acontece quando o proxy reproduz uma saída premium encontrada pelo foura_proxy ou foura_auto.

Cada um fica ausente quando a API não reporta nada, permitindo que um cliente desenvolvido para uma versão anterior continue funcionando sem alterações. Os mesmos valores estão documentados em Response Headers.

Clientes compatíveis com structuredContent podem passar o objeto tipado diretamente para o LLM, em vez de exigir que ele analise JSON a partir de texto corrido.

Headers de resposta com múltiplos valores

Headers que aparecem várias vezes (Set-Cookie, Link, WWW-Authenticate) retornam como arrays:

{
  "headers": [
    {
      "result": { "version": "HTTP/2", "code": 200, "reason": "" },
      "content-type": "text/html",
      "set-cookie": ["a=1; Path=/", "b=2; Path=/"]
    }
  ]
}

Isso é importante para sites que definem cookies de sessão + rastreamento + consentimento em uma única resposta (a maioria dos e-commerces).

Respostas grandes: offload_large (padrão: inline)

Por padrão (desde a v0.2.0), os corpos completos de resposta são retornados inline em structuredContent, independentemente do tamanho. Isso funciona em qualquer cliente MCP de imediato.

Se o seu cliente suporta MCP resources/read E você quer economizar tokens em páginas grandes, passe offload_large: true por chamada de ferramenta. Respostas >= 50 KB são gravadas em disco, retornadas como um resource_link, e seu cliente busca o corpo apenas quando realmente precisa dele. No servidor hospedado, payloads em cache expiram após 1 hora. Em sua própria instância, nada exclui payloads armazenados: limpe você mesmo os arquivos com mais de uma hora do diretório de payloads.

Um resultado descarregado inclui offloaded_resource_uri e size_bytes em vez do corpo. Um resultado descarregado também omite defense, e profile em foura_proxy, portanto ignore offload_large em uma chamada que leia esses campos.

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}
Cliente offload_large: true
Claude Desktop ainda não, deixe o padrão false
Claude Code, Cursor, Windsurf suportado
Extensão MCP do VS Code suportado

Isolado por tenant: cada chave de API recebe seu próprio namespace (sha256(apiKey)[:16]). Apenas a chave que armazenou um payload pode lê-lo de volta. Leituras entre tenants diferentes retornam Payload not found sem vazamento de existência.

Prompts Integrados

Seis modelos de fluxo de trabalho aparecem sob /prompts em qualquer cliente MCP. Cada um recebe argumentos nomeados e retorna uma mensagem de usuário baseada em template, orquestrando uma ou mais ferramentas.

Prompt Argumentos O que faz
smart_fetch url, opcional must_contain, extract Busca automática (escolhe o método, lida com proteção contra bots), depois retorna ou extrai o conteúdo
scrape_product_page url Busca via navegador, depois extrai título do produto, preço, imagem, estoque e SKU como JSON
extract_article url Busca simples com fallback para proxy, depois remove navegação/anúncios e retorna JSON limpo do artigo
monitor_pricing url, opcional target_price Busca via proxy, extrai o preço atual e compara com o valor de destino
check_endpoint_health url, opcional expected_text Busca simples com validação rigorosa, retorna acessibilidade e tempo de resposta
bulk_fetch_urls urls (separados por vírgula) Busca simples em paralelo, fallback automático para proxy por URL, retorna apenas metadados

Prompts custam zero tokens em repouso. Apenas prompts acionados entram no contexto do LLM.

Texto completo com prompts de fallback manual: Receitas de MCP.

Envelope de erro

Todo erro (isError: true) carrega um envelope structuredContent. Campos mínimos em cada erro:

{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

Em erros de upstream com status HTTP, status também está presente. Em erros de rate limit e capacidade, o envelope upstream adiciona retryAfter, current.{concurrency, rpm} e limits.{maxConcurrency, maxRpm}. Veja API Errors para o formato REST subjacente.

Valores estáveis de code:

Código HTTP Significado Seguro repetir?
ssrf_blocked n/d O destino é um endereço privado ou reservado (RFC 5735, 6598, IPv6 reservado), a URL não é http(s) ou seu hostname não foi resolvido Não, verifique a URL. Uma resolução que falhou brevemente pode ser repetida
upstream_non_json varia O upstream retornou corpo malformado Talvez, investigue
output_validation_failed n/d O outputSchema do servidor MCP rejeitou a resposta do upstream, ou a ferramenta não conseguiu concluir a chamada (nenhuma chave de API configurada, API inacessível) Talvez: verifique a configuração e depois reporte
bad_request 400 Formato de entrada rejeitado, a URL de destino aponta para a própria API do FourA em vez de uma página (apenas /inspect pode ser buscado lá), ou a URL tem um espaço não codificado (codifique como %20) Não, corrija os argumentos
auth_failed 401 Chave ausente, inválida ou desativada Não, corrija a chave
forbidden 403 O destino respondeu 403 e seu validate rejeitou (verificação de site, restrição de país) Não, ou mude para foura_proxy
not_found 404 Destino ou endpoint ausente Não
rate_limited 429 Limite de RPM atingido Sim, aguarde retryAfter
at_capacity 503 Limite de concorrência atingido, ou o serviço está desativado para manutenção (error indica Service disabled) Sim, aguarde retryAfter
service_disabled 503 Reservado. Um serviço desativado para manutenção retorna hoje como at_capacity, e uma ferramenta não inclusa no seu plano retorna como plan_limit_feature Entre em contato com o suporte
service_unavailable 503 503 genérico Sim, backoff curto
upstream_error 500+ ou 0 O destino respondeu com erro de servidor, ou em foura_proxy, foura_browser e foura_auto nunca responderam Sim, backoff exponencial
upstream_client_error 4xx Outro 4xx Geralmente não
upstream_unknown outro A requisição foi executada mas não produziu resposta aceita: em foura_single o destino nunca respondeu (timeout, conexão recusada), e em qualquer ferramenta seu validate rejeitou uma resposta 2xx ou 3xx. Leia status e error Investigue
no_eligible_proxy n/d Nenhum proxy corresponde ao escopo estrito de exitCountries Tente novamente mais tarde; altere o escopo apenas explicitamente
plan_limit_* 403 ou 429 Um dos limites do seu plano recusou a chamada: plan_limit_ seguido por feature, premium, concurrency, rate, browser_daily, credits ou bandwidth. Veja MCP Server Errors Aguarde retryAfter quando presente; caso contrário, apenas após o limite resetar ou o plano mudar

Agentes LLM podem ler code diretamente para lógica de retry sem analisar texto. Passo a passo de autenticação: Autenticação.

Limites

  • Body inline por padrão. Com offload_large: true, respostas >= 50 KB vão para o disco + resource_link (por tenant, TTL de 1 hora).
  • Destinos privados são recusados (RFC 5735, RFC 6598, blocos reservados IPv6) na camada MCP. Apenas hosts públicos são encaminhados.
  • Limite de body de request de 256 KB em requests /mcp de entrada (payloads MCP reais são < 4 KB).
  • Rate limits são aplicados pela FourA API por serviço. Consulte Rate Limits.

Auto-hospedagem

O código-fonte completo do servidor é público no GitHub sob @fouradata/mcp. Clone o repositório, execute npm install, npm run build e execute node dist/http.js para subir sua própria instância. Opera sem estado em um único contêiner atrás de qualquer balanceador de carga.

Ambiente configurável:

Variável Padrão Finalidade
PORT 3076 Porta de escuta HTTP
FOURA_API_BASE https://api.foura.ai/api URL base REST da FourA upstream
FOURA_MCP_PAYLOADS_DIR uma pasta foura-mcp-payloads no diretório temporário do sistema (o arquivo Docker Compose incluído define /data/payloads) Onde respostas >= 50 KB são armazenadas em cache no disco (com offload_large: true)
FOURA_MCP_ALLOWED_HOSTS mcp.foura.ai,localhost,127.0.0.1,[::1] Allowlist de hostnames para o header Host (defesa contra DNS rebinding)
FOURA_MCP_ALLOWED_ORIGINS https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com Allowlist de origens para chamadores via navegador

O contêiner oficial roda como uid 1001 (non-root). O arquivo Docker Compose incluído mantém /data/payloads em um volume nomeado; um bind mount do host nesse caminho deve ter permissão de escrita por esse uid.

Escale horizontalmente atrás de qualquer balanceador de carga. Os clientes fornecem sua chave a cada request, portanto não há sessão fixa. Com offload_large, aponte FOURA_MCP_PAYLOADS_DIR para um armazenamento compartilhado entre todas as instâncias, pois um payload armazenado fica no disco da instância que o gravou. GET /healthz responde com ok, name e version, permitindo que um balanceador de carga monitore a instância.

Atualizado em: 13 de novembro de 2026