Serveur MCP
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.
Démarrage rapide : stdio local (recommandé pour Claude Desktop)
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+Qsous 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 }avecmeta({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }, toujours présent, oùrungcorrespond à 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 égalementexitClass.meta.attemptsByEnginecompte les requêtes que l'appel a envoyées à Single, Proxy et Browser, etmeta.browserRequestscompte celles qui ont utilisé votre quota quotidien de Browser. Un échec inclut égalementattemptReport. Pas detotal_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 égalementexitCountry, une requête qui a nommé une classe inclutexitClass, une rotation qui a changé de famille de navigateur inclutprofile, et un échec inclutattemptReportfoura_browser: structure distincte{ status, headers: object, body, cookies, userAgent }(remarque :bodypeut ê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:premiumlorsqu'une sortie premium a traité l'appel. Surfoura_singleetfoura_browser, cela se produit lorsqueproxyrejoue une sortie premium identifiée parfoura_proxyoufoura_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.