Servidor MCP

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

Início Rápido: stdio local (recomendado para o Claude Desktop)

Obtenha uma chave em foura.ai/dashboard#api-keys (um clique, exibida apenas uma vez na criação, formato pk_live_...). Insira-a na 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 completamente o Claude Desktop (Cmd+Q no macOS) antes de editar o arquivo de configuração. Se o aplicativo ainda estiver em execução, ele substituirá suas edições com a configuração em memória ao sair.

O comando npx baixa o @fouradata/mcp na primeira inicialização (~10s) e o executa como um subprocesso do seu cliente MCP. Não é necessária uma instalação global.

Cliente	Onde a configuração fica
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 env primeiro)
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code (extensão MCP)	`.vscode/mcp.json`

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

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

Para clientes que suportam o transporte HTTP Streamable (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_..."
      }
    }
  }
}

As compilações atuais do Claude Desktop rejeitam o formato de url simples. Use a configuração stdio acima para o Claude Desktop ou faça a ponte através 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	HTTP Streamable (POST `/mcp`, SSE responses)
Autenticação	`Authorization: Bearer pk_live_...` por request
MCP-Protocol-Version	Por `@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", resource_metadata="https://foura.ai/docs/mcp/server#auth"`

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 três 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 allowlist: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Chamadores servidor para servidor (curl, clientes MCP no modo de ponte stdio) não enviam Origin e passam direto.

Ferramentas

Todas as três ferramentas são anotadas com readOnlyHint: true e openWorldHint: true conforme a especificação do MCP de 18-06-2025. Clientes que autoaprovam ferramentas confiáveis de apenas leitura as chamam sem um modal de confirmação por request.

foura_single

Um request HTTP, response de volta. 200ms a 2s. Espelha POST /api/single/ de um para um.

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

foura_proxy

Request HTTP roteado por um pool de proxy rotativo com retry automático. 1 a 5s. Espelha POST /api/proxy/.

Use quando o foura_single retornar 403, captcha ou conteúdo bloqueado geograficamente. O response inclui o ID do proxy que obteve sucesso (proxy) e o tempo total de relógio em segundos (total, float).

foura_browser

Sessão de browser completa. O JavaScript é executado, o DOM é renderizado, os cookies retornam. 2 a 10s. Espelha POST /api/browser/.

Use para single-page apps, conteúdo lazy-loaded ou páginas protegidas por desafios anti-bot que exigem um browser real para serem superadas.

Para formatos de entrada, padrões e regras de validação de cada ferramenta, consulte a referência do endpoint REST. Os esquemas das ferramentas correspondem campo a campo com a API REST, além do opt-in offload_large exclusivo do MCP (veja abaixo).

Responses tipados

Cada response de ferramenta inclui tanto o content (resumo de texto legível por humanos) quanto o structuredContent (JSON tipado validado contra o outputSchema da ferramenta). Cada ferramenta possui seu próprio formato exclusivo:

foura_single: { status, headers, data, total_time, ... } (headers é um array, uma entrada por hop de redirecionamento)
foura_proxy: igual ao single mais { proxy, total } (onde total é segundos em float, timing externo incluindo retries)
foura_browser: formato distinto { status, headers: object, body, cookies, userAgent } (nota: body pode ser uma string ou objeto dependendo do content-type)

Clientes que suportam structuredContent (Claude Desktop, Cursor, Windsurf a partir de 2026) passam o objeto tipado diretamente para o LLM, ignorando a re-tokenização de JSON como string. Espere uma economia de 30-40% de tokens em responses típicos.

Headers de response com múltiplos valores

Headers que aparecem múltiplas 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 um único response (a maior parte do e-commerce).

Responses grandes: `offload_large` (padrão: inline)

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

Se o seu cliente suportar resources/read do MCP E você quiser economizar tokens em páginas grandes, passe offload_large: true por chamada de ferramenta. Os responses ≥ 50 KB serão gravados em disco, retornados como um resource_link, e seu cliente buscará o corpo apenas quando realmente precisar dele. Os payloads em cache expiram após 1 hora.

{
  "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
VS Code MCP extension	suportado

Isolamento 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 retornam Payload not found sem vazamento de informações de existência.

Prompts integrados

Cinco templates de fluxo de trabalho aparecem em /prompts em qualquer cliente MCP. Cada um aceita argumentos nomeados e retorna uma mensagem de usuário baseada em template que orquestra uma ou mais ferramentas.

Prompt	Argumentos	O que faz
`scrape_product_page`	`url`	Busca via browser e, em seguida, extrai título do produto, preço, imagem, estoque e SKU como JSON
`extract_article`	`url`	Busca via single com fallback para proxy, depois remove navegação/anúncios e retorna o JSON limpo do artigo
`monitor_pricing`	`url`, `target_price` opcional	Busca via proxy, extrai o preço atual e compara com o preço-alvo
`check_endpoint_health`	`url`, `expected_text` opcional	Busca via single com validação estrita, retorna acessibilidade e tempo de resposta
`bulk_fetch_urls`	`urls` (separados por vírgula)	Busca paralela via single, com fallback automático para proxy por URL, retorna apenas metadados

Os prompts custam zero tokens quando ociosos. Apenas os prompts invocados entram no contexto do LLM.

Texto completo e prompts de fallback manuais: MCP Recipes.

Envelope de erro

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

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

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

Valores estáveis de code:

Code	HTTP	Significado	Seguro para retry?
`ssrf_blocked`	n/a	IP de destino em uma faixa privada ou reservada (RFC 5735, 6598, IPv6 reservado)	Não, altere a URL
`upstream_non_json`	varia	O upstream retornou um corpo malformado	Talvez, investigue
`output_validation_failed`	n/a	O `outputSchema` do servidor MCP rejeitou o response do upstream (bug do servidor ou formato inesperado do upstream)	Talvez, reporte
`bad_request`	400	Formato de entrada rejeitado	Não, corrija os argumentos
`auth_failed`	401	Chave ausente, inválida ou desativada	Não, corrija a chave
`forbidden`	403	Autenticado, mas não permitido	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	Sim, aguarde `retryAfter`
`service_disabled`	503	Janela de manutenção ou seu plano não inclui esta ferramenta	Entre em contato com o suporte
`service_unavailable`	503	503 genérico	Sim, backoff curto
`upstream_error`	500+	Upstream 5xx	Sim, backoff exponencial
`upstream_client_error`	4xx	Outro 4xx	Geralmente não
`upstream_unknown`	outro	Defensivo, não deve ocorrer na prática	Investigue

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

Limites

Corpo inline por padrão. Com offload_large: true, responses ≥ 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 do MCP. Apenas hosts públicos são encaminhados.
Limite de corpo de request de 256 KB em requests /mcp de entrada (payloads reais do MCP são < 4 KB).
Os rate limits são aplicados pela API do FourA por serviço. Consulte Rate Limits.

Self-Hosting

Cada instância é executada em um container de forma stateless. Um espelho público no GitHub chegará com a v1.0. Até lá, o código-fonte está em um repositório privado e a imagem do container está disponível mediante solicitação. Entre em contato com support@foura.ai para obter acesso antecipado.

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 do FourA upstream
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	Onde responses ≥ 50 KB são armazenados 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 origins para chamadores via browser
`FOURA_MCP_RESOURCE_METADATA_URL`	`https://foura.ai/docs/mcp/server#auth`	URL retornada no `WWW-Authenticate` em caso de 401

Executado como uid 1001 (não root) no container oficial. O ponto de montagem bind do host /data/payloads deve ter permissão de escrita para esse uid.

Dimensione horizontalmente atrás de qualquer balanceador de carga. Os clientes fornecem sua chave em cada request, portanto não há necessidade de sticky session.

Atualizado em: 1 de julho de 2026

Servidor MCP

Servidor MCP

Início Rápido: stdio local (recomendado para o Claude Desktop)

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

Referência do endpoint hospedado

Ferramentas

foura_single

foura_proxy

foura_browser

Responses tipados

Headers de response com múltiplos valores

Responses grandes: offload_large (padrão: inline)

Prompts integrados

Envelope de erro

Limites

Self-Hosting

Responses grandes: `offload_large` (padrão: inline)