Serveur MCP

Utilisez FourA depuis n'importe quel client Model Context Protocol (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) sous forme de quatre outils natifs et six prompts de workflow. Aucun code d'intégration, aucun client HTTP personnalisé.

Open source sur GitHub ; disponible sur npm sous le nom @fouradata/mcp. Version actuelle : 0.8.3.

Obtenez une clé sur foura.ai/dashboard#api-keys (en un clic, format pk_live_..., et Reveal réaffiche la clé plus tard). Ajoutez ceci à la configuration de votre client MCP :

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

Piège avec Claude Desktop : quittez complètement Claude Desktop (Cmd+Q sous macOS) avant de modifier le fichier de configuration. Si l'application est toujours en cours d'exécution, elle écrasera vos modifications avec sa configuration en mémoire lors de sa fermeture.

La commande npx télécharge @fouradata/mcp au premier lancement et l'exécute en tant que sous-processus de votre client MCP. Aucune installation globale n'est requise.

Client Emplacement de la configuration
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 (définissez d'abord FOURA_API_KEY dans l'environnement)
Cursor ~/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
VS Code (extension MCP) .vscode/mcp.json, sous une clé racine servers au lieu de mcpServers

Redémarrez le client. Les outils (foura_auto, foura_single, foura_proxy, foura_browser) et six prompts apparaissent dans votre liste d'outils.

Démarrage rapide : hébergé (Streamable HTTP)

Pour les clients qui prennent en charge le transport Streamable HTTP (Cursor, Windsurf, VS Code, Claude Code avec --transport http), faites-les pointer vers l'endpoint hébergé au lieu d'exécuter un sous-processus local :

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

Pour Claude Desktop, utilisez la configuration stdio ci-dessus ou reliez l'endpoint hébergé via mcp-remote :

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

Référence de l'endpoint hébergé

Propriété Valeur
URL https://mcp.foura.ai/mcp
Transport Streamable HTTP (POST /mcp, réponses SSE)
Authentification Authorization: Bearer pk_live_... par request. Une clé brute dans Authorization, ou X-API-Key: pk_live_..., fonctionne également
MCP-Protocol-Version Selon @modelcontextprotocol/sdk (actuellement 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)
Challenge 401 WWW-Authenticate: Bearer realm="foura-mcp"

Le challenge 401 ne comporte aucun paramètre RFC 9728 resource_metadata, à dessein. En annoncer un inciterait un client compatible OAuth à lancer un flux que ce serveur n'implémente pas. Envoyez votre clé pk_live_ sous forme de Bearer token et l'erreur 401 disparaît.

Le serveur hébergé est stateless. Chaque request apporte sa propre clé, que le serveur transmet à l'API FourA en tant que X-API-Key. Une seule clé déverrouille les quatre outils.

Pour se protéger contre le DNS-rebinding (CVE-2025-66414), le serveur valide le header Host (doit être mcp.foura.ai ou localhost) et le header Origin lorsqu'il est présent (liste autorisée : mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Les appelants de serveur à serveur (curl, clients MCP en mode pont stdio) n'envoient aucun Origin et passent sans encombre.

Outils

Les quatre outils sont annotés readOnlyHint: true et openWorldHint: true conformément à la spécification MCP 2025-06-18. Les clients qui approuvent automatiquement les outils fiables en lecture seule les appellent sans fenêtre modale de confirmation à chaque request.

foura_auto est le choix intelligent par défaut : fournissez-lui une URL et il renvoie le contenu, en choisissant la méthode de récupération à votre place. Les trois autres sont les primitives de niveau inférieur qu'il orchestre ; utilisez-les lorsque vous souhaitez un contrôle explicite.

foura_auto

Fournissez-lui une URL lorsque vous souhaitez que FourA choisisse la méthode de request. Il effectue un nombre limité de tentatives sur les différents chemins HTTP, proxy et navigateur disponibles. Transmettez validate sur les cibles protégées afin que la response contienne impérativement un contenu identifiant la page réelle. Si aucune tentative ne satisfait la validation, l'outil renvoie une erreur au lieu de présenter une page de challenge comme un succès.

La response inclut les détails d'exécution dans meta et, par défaut, une session réutilisable avec proxy, cookies et userAgent. Pour un suivi simple, appelez foura_single avec session.proxy comme proxy, sérialisez les cookies sous forme de header Cookie et envoyez session.userAgent comme header User-Agent. Pour le rendu JavaScript, transmettez les valeurs de session aux champs foura_browser correspondants.

Définissez exitClass: "premium" pour permettre à Auto de basculer vers une sortie premium dès que le pool standard ne parvient pas à atteindre la page. exitClass: "standard" et l'omission du champ maintiennent tous deux Auto sur le pool standard, et seule une requête qui spécifie une classe reçoit exitClass en retour. Le fonctionnement est identique à foura_proxy: une autorisation, pas une instruction, décomptée du trafic premium de votre forfait, et refusée avec code: "plan_limit_premium" sur un forfait sans sorties premium. Le champ exitClass du résultat indique la classe qui a délivré la réponse. Consultez exitClass on Smart Fetch.

foura_single

Une requête HTTP, une réponse en retour. Reproduit fidèlement POST /api/single/.

À utiliser pour les pages statiques, les API JSON, le HTML généré côté serveur.

Choisir le navigateur que vous présentez

Une requête présente par défaut la dernière version de Google Chrome. Lorsqu'une cible accepte un navigateur et en refuse un autre, définissez browser (Chrome, Edge, Safari, Firefox ou Tor), os (Windows, macOS, Android ou iOS), ou version, ou transmettez un identifiant profile exact :

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

La version la plus récente l'emporte lorsque plusieurs profils correspondent. Une combinaison qui n'existe pas renvoie une erreur listant ce qui est disponible, garantissant ainsi qu'une request n'est jamais envoyée sous l'identité d'un navigateur que vous n'avez pas choisi. La sélection nécessite unblocker, activé par défaut. Le catalogue est publié à l'adresse GET /api/profiles et ne nécessite aucune clé d'API.

Les quatre mêmes champs se trouvent dans l'objet request de foura_proxy.

foura_proxy

Acheminez une request HTTP via des proxies tournants avec nouvelle tentative automatique. Utilisez-le lorsque foura_single est bloqué ou que la cible requiert un pays de sortie spécifique.

Définissez exitCountries avec une liste stricte de codes pays à deux lettres visibles par la cible, fournis par l'utilisateur ou imposés par la cible :

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

Les valeurs sont nettoyées des espaces, converties en majuscules et dédupliquées. Les sorties du pool standard dont le pays est inconnu sont exclues, et le pool standard ne bascule jamais vers un pays non demandé. Une sortie premium reste également dans cette liste: avec exitClass: "premium", le pool standard reste prioritaire, et une sortie premium provient de l'un de vos pays et l'indique dans exitCountry. La sélection utilise les métadonnées de pays visibles par la cible les plus récentes disponibles, normalement mises à jour dans un délai de dix minutes; il ne s'agit pas d'une recherche de géolocalisation en direct pendant la requête. Ne déduisez pas le pays de desserte à partir de l'adresse de l'hôte proxy.

Un succès ciblé renvoie exitCountry et l'ID réutilisable proxy. Vérifiez que exitCountry appartient à la liste d'autorisation demandée. Si le pool actuel ne contient aucune correspondance, l'outil renvoie code: "no_eligible_proxy" avec la portée normalisée dans details.exitCountries. Conservez cette portée et réessayez plus tard. Ne la modifiez ou ne l'élargissez que si l'utilisateur change explicitement l'exigence. Le ciblage par pays est inclus à partir du forfait Startup. Sur un forfait qui ne l'inclut pas, un appel envoyant exitCountries est refusé avec un code 403 et X-FourA-Limit: plan_limit_feature.

Si la page sélectionnée nécessite ultérieurement JavaScript, transmettez l'ID proxy renvoyé à foura_browser.proxy afin que le navigateur réutilise la même sortie.

Définissez exitClass: "premium" pour une cible que le pool standard ne peut pas atteindre, quel que soit le nombre de sorties essayées. Il s'agit d'une autorisation, pas d'une instruction: le pool standard tente toujours d'obtenir la réponse en premier et l'emporte généralement, et une requête à laquelle il répond avant qu'aucune sortie premium ne soit tentée ne consomme aucun trafic premium. Une tentative premium comptabilise le trafic qu'elle a transporté, même en cas d'échec. La réponse renvoie exitClass, premium ou standard, ce qui vous permet de voir par requête quelle classe vous a servi. standard est également la réponse dès que le volume de trafic premium inclus dans votre forfait est épuisé, et il s'agit d'un résultat normal plutôt que d'une erreur. exitClass: "standard" interdit formellement l'escalade. exitClass: "premium" sur un forfait sans sorties premium est refusé avec code: "plan_limit_premium". Consultez exitClass.

Lorsque la rotation a dû changer de navigateur pour obtenir une réponse, une réponse réussie contient profile: l'identifiant du profil de catalogue retenu. Transmettez-le sous le nom profile lors de l'appel suivant pour présenter le même navigateur.

Une rotation ayant échoué contient attemptReport à côté de l'erreur: une phrase summary, ainsi que des compteurs qui séparent les sorties qui n'ont jamais répondu (noResponse), les sorties refusées par une vérification de bot (defense, avec les fournisseurs dans vendors), les pages arrivées et rejetées uniquement par votre propre règle validate.data (contentRejected), statusRejected, et other. profilesTried répertorie les navigateurs envoyés par la tâche, par ordre de première utilisation, default signifiant que la requête est partie exactement comme rédigée. Une valeur élevée pour contentRejected signifie que FourA a livré de vraies pages et que votre propre règle les a rejetées. Consultez Why a Proxy Request Ran Out of Tries.

foura_browser

Session de navigateur complète. Le JavaScript s'exécute, le DOM effectue son rendu, les cookies sont renvoyés. Reproduit POST /api/browser/.

À utiliser pour les applications monopages, le contenu en lazy-loading ou les pages avec une vérification nécessitant un vrai navigateur pour aboutir.

Pour la structure des entrées, les valeurs par défaut et les règles de validation de chaque outil, consultez la référence des endpoints REST. Les schémas d'outils correspondent à l'API REST, avec en plus l'option réservée à MCP offload_large (voir ci-dessous), avec deux exceptions : foura_browser ne possède pas de champ lean, et foura_proxy ne possède pas encore de champs de localisation de sortie. Une valeur envoyée sous ces noms n'atteint jamais l'API. Pour en définir une, appelez directement POST /api/browser/ ou POST /api/proxy/.

Lorsqu'une cible exécute une vérification de bot

foura_single et foura_proxy renvoient defense lorsque la cible a exécuté une vérification de bot avant d'accéder au body. defense.solved: true signifie que la vérification a réussi et que data correspond à la vraie page ; false signifie que le body peut être une page de challenge. Réessayez avec un navigateur, un système d'exploitation ou une version différents, ou passez à foura_proxy ou foura_browser, au lieu de traiter la page de challenge comme du contenu.

Réponses typées

Chaque réponse d'outil inclut à la fois content (résumé textuel lisible par l'utilisateur) et structuredContent (JSON typé validé par rapport au outputSchema de l'outil). Chaque outil a sa propre structure :

  • foura_auto : structure unique { status, headers, data } avec meta ({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }, toujours présent, où rung correspond à l'un des éléments suivants : cache, probe, proxy, browser, warmup, fail) et, par défaut, session ({ proxy, cookies, userAgent }) pour le rejeu via les outils de niveau inférieur ; une requête qui a nommé une classe inclut également exitClass. meta.attemptsByEngine compte les requêtes que l'appel a envoyées à Single, Proxy et Browser, et meta.browserRequests compte celles qui ont utilisé votre quota quotidien de Browser. Un échec inclut également attemptReport. Pas de total_time.
  • foura_single : { status, headers, data, total_time, ... } (headers est un tableau, avec une entrée par saut de redirection)
  • foura_proxy : identique à single avec en plus { proxy, total } ; un succès délimité inclut également exitCountry, une requête qui a nommé une classe inclut exitClass, une rotation qui a changé de famille de navigateur inclut profile, et un échec inclut attemptReport
  • foura_browser : structure distincte { status, headers: object, body, cookies, userAgent } (remarque : body peut être une chaîne ou un objet selon le content-type)

Chaque outil indique également ce que l'appel a coûté et comment le tracer, lu à partir des en-têtes de réponse de l'API :

  • credits : crédits consommés par cet appel. Présent également en cas d'échec, car le traitement a bien été effectué. Vous n'êtes facturé que pour un appel réussi, un échec affiche donc ses crédits ici mais ne vous coûte rien.
  • request_id : identifiant FourA de l'appel. Mentionnez-le dans vos demandes d'assistance.
  • exitClass : premium lorsqu'une sortie premium a traité l'appel. Sur foura_single et foura_browser, cela se produit lorsque proxy rejoue une sortie premium identifiée par foura_proxy ou foura_auto.

Chacun est absent lorsque l'API ne renvoie rien, garantissant ainsi qu'un client conçu pour une version antérieure continue de fonctionner sans modification. Les mêmes valeurs sont documentées sous Response Headers.

Les clients prenant en charge structuredContent peuvent transmettre directement l'objet typé au LLM, sans exiger qu'il extrait le JSON du texte brut.

En-têtes de réponse à valeurs multiples

Les en-têtes qui apparaissent plusieurs fois (Set-Cookie, Link, WWW-Authenticate) sont renvoyés sous forme de tableaux :

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

Cela est important pour les sites qui définissent des cookies de session, de suivi et de consentement dans une seule response (la majorité des sites e-commerce).

Réponses volumineuses : offload_large (par défaut : inline)

Par défaut (depuis la version 0.2.0), les corps de response complets sont renvoyés inline dans structuredContent quelle que soit leur taille. Cela fonctionne immédiatement avec tous les clients MCP.

Si votre client prend en charge MCP resources/read ET que vous souhaitez économiser des tokens sur les pages volumineuses, transmettez offload_large: true à chaque appel d'outil. Les responses >= 50 Ko sont alors écrites sur le disque, renvoyées sous la forme d'un resource_link, et votre client ne récupère le body que lorsqu'il en a réellement besoin. Sur le serveur hébergé, les payloads en cache expirent après 1 heure. Sur votre propre instance, rien ne supprime les payloads stockés : nettoyez vous-même les fichiers de plus d'une heure dans le répertoire des payloads.

Un résultat déporté contient offloaded_resource_uri et size_bytes à la place du body. Un résultat déporté omet également defense, ainsi que profile sur foura_proxy, évitez donc offload_large lors d'un appel qui lit ces champs.

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}
Client offload_large: true
Claude Desktop pas encore, laissez false par défaut
Claude Code, Cursor, Windsurf pris en charge
Extension VS Code MCP pris en charge

Isolé par tenant : chaque clé API obtient son propre espace de noms (sha256(apiKey)[:16]). Seule la clé ayant stocké une charge utile peut la relire. Les lectures inter-tenants renvoient Payload not found sans fuite d'existence.

Prompts intégrés

Six modèles de workflow apparaissent sous /prompts dans n'importe quel client MCP. Chacun accepte des arguments nommés et renvoie un message utilisateur sous forme de modèle orchestrant un ou plusieurs outils.

Prompt Arguments Description
smart_fetch url, facultatif must_contain, extract Récupération automatique (sélectionne la méthode, gère la protection anti-bot), puis renvoie ou extrait le contenu
scrape_product_page url Récupération par navigateur, puis extrait le titre du produit, le prix, l'image, le stock, le SKU au format JSON
extract_article url Requête unique avec repli sur proxy, puis supprime la navigation/les publicités et renvoie un JSON d'article nettoyé
monitor_pricing url, facultatif target_price Récupération par proxy, extrait le prix actuel, compare à la cible
check_endpoint_health url, facultatif expected_text Requête unique avec validation stricte, renvoie l'accessibilité et les temps de réponse
bulk_fetch_urls urls (séparés par des virgules) Requêtes uniques en parallèle, repli automatique sur proxy par URL, renvoie uniquement les métadonnées

Les prompts ne consomment aucun token au repos. Seuls les prompts invoqués entrent dans le contexte du LLM.

Texte intégral et prompts de repli manuel : Recettes MCP.

Enveloppe d'erreur

Chaque erreur (isError: true) comporte une enveloppe structuredContent. Champs minimaux pour chaque erreur :

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

En cas d'erreurs en amont avec un code HTTP, status est également présent. Pour les erreurs de rate limit et de capacité, l'enveloppe amont ajoute retryAfter, current.{concurrency, rpm} et limits.{maxConcurrency, maxRpm}. Consultez API Errors pour la structure REST sous-jacente.

Valeurs stables de code :

Code HTTP Signification Nouvelle tentative sans risque ?
ssrf_blocked n/a La cible est une adresse privée ou réservée (RFC 5735, 6598, IPv6 réservé), l'URL n'est pas http(s), ou son nom d'hôte n'a pas pu être résolu Non, vérifiez l'URL. Une résolution ayant échoué brièvement peut être retentée
upstream_non_json variable Le serveur en amont a renvoyé un corps de réponse malformé Peut-être, examinez le problème
output_validation_failed n/a Le outputSchema du serveur MCP a rejeté la réponse en amont, ou l'outil n'a pas pu terminer l'appel (aucune clé API configurée, API inaccessible) Peut-être : vérifiez la configuration, puis signalez l'incident
bad_request 400 Format d'entrée rejeté, l'URL cible pointe vers l'API interne de FourA au lieu d'une page (seul /inspect peut y être récupéré), ou l'URL contient un espace non encodé (encodez-le sous la forme %20) Non, corrigez les arguments
auth_failed 401 Clé manquante, invalide ou désactivée Non, corrigez la clé
forbidden 403 La cible a répondu 403 et votre validate l'a rejetée (vérification du site, restriction géographique) Non, ou passez à foura_proxy
not_found 404 Cible ou endpoint introuvable Non
rate_limited 429 Limite de RPM atteinte Oui, attendez retryAfter
at_capacity 503 Limite de concurrence atteinte, ou service temporairement désactivé pour maintenance (error indique Service disabled) Oui, attendez retryAfter
service_disabled 503 Réservé. Un service désactivé pour maintenance renvoie actuellement at_capacity, et un outil non inclus dans votre forfait renvoie plan_limit_feature Contactez le support
service_unavailable 503 503 générique Oui, court backoff
upstream_error 500+ ou 0 La cible a répondu par une erreur de serveur, ou sur foura_proxy, foura_browser et foura_auto n'ont jamais répondu Oui, backoff exponentiel
upstream_client_error 4xx Autre 4xx Généralement non
upstream_unknown autre La requête a été exécutée mais n'a produit aucune réponse acceptée : sur foura_single la cible n'a jamais répondu (timeout, connexion refusée), et sur n'importe quel outil votre validate a rejeté une réponse 2xx ou 3xx. Consultez status et error Examinez le problème
no_eligible_proxy n/a Aucun proxy ne correspond au périmètre strict de exitCountries Réessayez plus tard ; ne modifiez le périmètre que de manière explicite
plan_limit_* 403 ou 429 L'une des limites de votre forfait a refusé l'appel : plan_limit_ suivi de feature, premium, concurrency, rate, browser_daily, credits ou bandwidth. Consultez MCP Server Errors Attendez retryAfter si présent ; sinon, attendez la réinitialisation de la limite ou la mise à niveau du forfait

Les agents LLM peuvent lire code directement pour la logique de nouvelle tentative sans analyser de texte. Guide d'authentification : Authentication.

Limites

  • Corps de texte en ligne par défaut. Avec offload_large: true, les réponses >= 50 Ko sont écrites sur disque + resource_link (par tenant, TTL de 1 heure).
  • Les cibles privées sont refusées (RFC 5735, RFC 6598, blocs réservés IPv6) au niveau de la couche MCP. Seuls les hôtes publics sont transmis.
  • Limite de taille du corps de requête fixée à 256 Ko pour les requêtes entrantes /mcp (les charges utiles MCP réelles font < 4 Ko).
  • Les rate limits sont appliquées par l'API FourA par service. Consultez Rate Limits.

Auto-hébergement

Le code source complet du serveur est public sur GitHub sous @fouradata/mcp. Clonez le dépôt, npm install, npm run build, et exécutez node dist/http.js pour déployer votre propre instance. Fonctionne sans état dans un conteneur unique derrière n'importe quel équilibreur de charge.

Environnement configurable :

Variable Par défaut Rôle
PORT 3076 Port d'écoute HTTP
FOURA_API_BASE https://api.foura.ai/api URL de base REST amont FourA
FOURA_MCP_PAYLOADS_DIR un dossier foura-mcp-payloads dans le répertoire temporaire du système (le fichier Docker Compose fourni définit /data/payloads) Emplacement où les réponses >= 50 Ko sont mises en cache sur disque (avec offload_large: true)
FOURA_MCP_ALLOWED_HOSTS mcp.foura.ai,localhost,127.0.0.1,[::1] Liste d'autorisation de noms d'hôte pour l'en-tête Host (protection contre le rebinding DNS)
FOURA_MCP_ALLOWED_ORIGINS https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com Liste d'autorisation Origin pour les appelants de navigateur

Le conteneur officiel s'exécute en tant que uid 1001 (non-root). Le fichier Docker Compose fourni conserve /data/payloads sur un volume nommé ; un montage de type bind de l'hôte dans ce chemin doit être accessible en écriture par cet uid.

Échelonnez horizontalement derrière n'importe quel équilibreur de charge. Les clients fournissent leur clé à chaque requête, il n'y a donc pas de session persistante. Avec offload_large, pointez FOURA_MCP_PAYLOADS_DIR vers un stockage partagé par toutes les instances, car une charge utile stockée réside sur le disque de l'instance qui l'a écrite. GET /healthz répond avec ok, name et version, afin qu'un équilibreur de charge puisse sonder une instance.

Mis à jour : 13 novembre 2026