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.
Início rápido: stdio local (recomendado para Claude Desktop)
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+Qno 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 }maismeta({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }, sempre presente, onderungé um entrecache,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 incluiexitClass.meta.attemptsByEngineconta as requisições que a chamada enviou para Single, Proxy e Browser, emeta.browserRequestsconta aquelas que consumiram sua cota diária de Browser. Uma falha também incluiattemptReport. Semtotal_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 incluiexitCountry, uma requisição que definiu uma classe incluiexitClass, uma rotação que alterou a família do navegador incluiprofile, e uma falha incluiattemptReportfoura_browser: estrutura distinta{ status, headers: object, body, cookies, userAgent }(observação:bodypode 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-premiumquando uma saída premium atendeu à chamada. Nofoura_singlee nofoura_browser, isso acontece quando oproxyreproduz uma saída premium encontrada pelofoura_proxyoufoura_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
/mcpde 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.