Connecter Firecrawl

Les offres, limites, versions et outils exposés par Firecrawl évoluent. Ce cours présente le chemin de référence recommandé (à jour au 6 septembre 2026). Vérifie la documentation et les conditions du compte avant la mise en production ou le traitement de données sensibles.

Pourquoi tu fais ça

Firecrawl donne à ton IA un accès structuré au web. Elle peut rechercher des sources, lire une page publique et parcourir un ensemble limité de pages sans que tu aies à copier manuellement leur contenu dans OpenCode.

Pour toi, cette connexion sert notamment à préparer une veille, comparer des offres, lire une documentation ou collecter les sources d’une analyse. Firecrawl fournit le contenu disponible sur le web. Le modèle reste responsable de l’analyse demandée, et tu restes responsable de la décision et de la vérification des sources.

Firecrawl est un service externe. Les URL demandées et les contenus récupérés passent par son infrastructure, puis peuvent être transmis au provider LLM actif dans OpenCode. Ne l’utilise pas sur une page privée, un espace client ou une URL contenant un token sans avoir validé ce flux de données.

Objectif

À la fin de ce cours, tu sais :

• expliquer ce que Firecrawl apporte au Core System ;
• distinguer Scrape, Search et Crawl ;
• créer un compte et une clé API de test ;
• conserver cette clé dans ton gestionnaire de secrets ;
• connecter le MCP Firecrawl avec /connect-tool, sans écrire la clé dans le vault ou la conversation ;
• tester la connexion sur des pages publiques ;
• cadrer une recherche web utile à une décision d’entreprise ;
• désactiver l’accès ou révoquer la clé si nécessaire.

Avant de commencer

Tu dois avoir terminé :

• Installation technique ;
• Comment utiliser OpenCode Desktop ;
• Gestionnaire de secrets et connexions sécurisées.

Prépare également :

• OpenCode ouvert sur le bon Workspace ;
• 1Password et sa CLI fonctionnels, ou le parcours Bitwarden Secrets Manager validé ;
• Node.js 22 ou une version ultérieure, avec npm et npx disponibles ;
• une page publique et non sensible pour le test ;
• l’autorisation de créer un compte Firecrawl en ton nom ou au nom de ton entreprise.

Vérifie Node.js dans Terminal :

node --version

Si la version est antérieure à 22 ou si la commande ne répond pas, termine d’abord l’installation avec le responsable technique. Ne contourne pas le blocage en copiant la clé dans un fichier de configuration.

1. Comprendre les trois modes principaux

Mode	Ce qu’il fait	Quand l’utiliser	Réflexe de contrôle
Scrape	Extrait le contenu d’une URL précise dans un format exploitable	Lire une page d’offre, un article ou une documentation	Vérifier l’URL et la date de la page
Search	Recherche des pages pertinentes à partir d’une requête	Identifier des sources, des concurrents ou des informations récentes	Demander les liens et recouper les affirmations importantes
Crawl	Parcourt plusieurs pages d’un site à partir d’une URL	Collecter une documentation ou une section de site	Limiter les chemins, la profondeur et le nombre de pages

Commence par Scrape. Il porte sur une page connue, donc son périmètre et sa consommation sont plus faciles à vérifier. Utilise Search lorsque tu ne connais pas encore les bonnes sources. Réserve Crawl à un objectif précis et borné.

Firecrawl peut exposer d’autres outils selon la connexion, la version et le plan, notamment Map, Parse, l’extraction structurée ou des agents de recherche. Ils ne sont pas nécessaires pour valider ce premier cours.

2. Créer le compte et la clé API

Étape 1 : créer le compte

1. Ouvre le site officiel de Firecrawl.
2. Clique sur Get Started ou ouvre la page de création de compte.
3. Crée le compte avec l’adresse professionnelle retenue pour le pilote.
4. Active la double authentification si elle est proposée.
5. Identifie le propriétaire du compte et le moyen de récupération dans la documentation interne de l’entreprise, sans y inscrire de secret.

N’utilise pas le compte personnel d’un collaborateur si la connexion doit devenir un outil durable de l’entreprise.

Étape 2 : vérifier le plan et la consommation

À la date de revue du cours, Firecrawl annonce un plan gratuit de 1 000 crédits par mois, sans carte, correspondant notamment à environ 1 000 pages scrapées. Les tarifs, quotas et règles de consommation peuvent changer.

Pour bien commencer :

1. commence avec le plan gratuit ;
2. désactive ou plafonne toute dépense automatique si une option payante est activée plus tard ;
3. vérifie le solde avant un crawl ;
4. documente qui peut décider d’un changement de plan.

Étape 3 : générer une clé de test

1. Dans Firecrawl, ouvre API Keys.
2. Crée une clé dédiée au pilote.
3. Donne-lui un nom reconnaissable, par exemple opencode-perso.
4. Copie sa valeur une seule fois vers le coffre prévu à l’étape suivante.
5. Ne colle pas cette valeur dans OpenCode, Obsidian, Slack, un email ou une capture.

Une clé Firecrawl commence généralement par fc-. Ce préfixe peut être montré pour reconnaître le type de secret. La valeur complète ne doit jamais apparaître dans le support de formation ou la preuve de validation.

3. Placer la clé dans le coffre

Le parcours de référence utilise l’Environment créé dans le cours précédent.

1. Ouvre 1Password.
2. Ouvre l’Environment de test, par exemple opencode-test.
3. Ajoute ou vérifie la variable FIRECRAWL_API_KEY.
4. Colle la clé directement dans son champ de valeur.
5. Vérifie que la valeur est masquée.
6. Copie uniquement l’Environment ID pour la prochaine étape.

Le flux attendu est :

La clé ne doit être présente ni dans opencode.json, ni dans AGENTS.md, ni dans le Business Brain. Si tu utilises Bitwarden Secrets Manager, applique le même principe avec bws run, comme décrit dans le cours précédent.

4. Installer le MCP avec /connect-tool

Dans OpenCode, lance :

/connect-tool firecrawl

Quand le skill demande le mode de connexion, choisis une connexion liée à ton installation personnelle. Indique où le secret est injecté, sans donner sa valeur.

Tu peux formuler la demande ainsi :

Connecte Firecrawl à OpenCode sous le nom firecrawl.
Utilise le MCP local officiel et vérifie d'abord sa version actuelle.
La variable FIRECRAWL_API_KEY est stockée dans mon Environment 1Password <ENVIRONMENT_ID>.
Lance le MCP avec op run, sans écrire ni afficher la clé.
Vérifie que Node.js 22 ou une version ultérieure est disponible.
Explique les fichiers de configuration modifiés et attends ma validation avant de les modifier.
Après installation, teste uniquement https://example.com en lecture seule.

Connect Tool doit vérifier la documentation actuelle et construire une configuration dont la logique est :

op run --environment <ENVIRONMENT_ID> -- npx -y firecrawl-mcp@<VERSION_VALIDEE>

La version du package doit être celle vérifiée au moment de l’installation. Ne recopie pas aveuglément une version présente dans ce cours ou dans une ancienne configuration.

Avant de valider le plan proposé par Connect Tool, vérifie :

• le nom firecrawl ;
• la portée de la configuration, globale ou limitée au workspace ;
• la commande officielle utilisée ;
• la présence du nom de variable FIRECRAWL_API_KEY sans sa valeur ;
• l’absence de clé dans les fichiers et les logs ;
• le test de lecture seule prévu ;
• la méthode de désactivation et de révocation.

Après la modification, ferme complètement OpenCode puis relance-le. Un MCP ajouté à la configuration peut ne pas apparaître dans une session déjà ouverte.

5. Vérifier la connexion

Test 1 : Scrape

Demande :

Avec Firecrawl, scrape uniquement https://example.com.
Donne le titre de la page et une phrase qui résume son contenu.
N'utilise aucun autre outil, ne modifie aucun fichier et ne révèle aucun credential.

Le résultat attendu contient le titre Example Domain et un résumé cohérent. Dans la liste des appels d’outils, vérifie que Firecrawl a bien été utilisé.

Test 2 : Search

Demande :

Avec Firecrawl, recherche la documentation officielle actuelle du MCP Firecrawl.
Retourne les trois résultats les plus pertinents avec leur titre, leur URL et leur date si elle est disponible.
Sépare les faits trouvés de tes conclusions.

Ouvre au moins un lien officiel et vérifie qu’il correspond au titre annoncé. Une synthèse sans URL ne constitue pas une preuve de recherche.

Test 3 : Crawl limité

Demande :

Prépare un crawl limité de https://docs.firecrawl.dev/mcp-server.
Limite-le à 5 pages et aux chemins liés au MCP.
Avant de lancer le crawl, montre le périmètre, la limite et le résultat attendu, puis attends ma validation.

Valide seulement si le plan reste borné. Après exécution, vérifie le nombre de pages réellement traitées et la consommation dans le tableau de bord Firecrawl.

6. Formuler une demande web fiable

Une bonne demande précise :

1. la question métier à éclairer ;
2. le périmètre des sources ;
3. la période utile ;
4. le nombre maximal de résultats ou de pages ;
5. le format de sortie ;
6. la nécessité de citer les URL ;
7. l’action interdite ou soumise à validation.

Exemple :

Recherche les annonces officielles publiées ces 30 derniers jours par les trois concurrents nommés dans la note de positionnement du projet actif.
Utilise leurs sites officiels comme sources principales.
Pour chaque annonce, donne la date, le lien, le fait observable et l'impact possible pour notre positionnement.
Signale les informations non vérifiées.
Crée d'abord un plan et ne modifie aucune note avant ma validation.

Firecrawl récupère des sources. Il ne garantit ni leur exactitude, ni leur neutralité, ni leur actualité. Le modèle peut aussi mal interpréter un contenu correctement récupéré. Pour une décision importante, ouvre les sources primaires et recoupe les faits déterminants.

7. Cas d’usage

Veille de marché

Recherche cinq annonces récentes sur le marché de l'IA pour les PME francophones.
Privilégie les sources officielles et indique la date de chaque publication.
Résume chaque annonce en trois points : fait, impact potentiel, question à vérifier.
Propose ensuite une note de veille dans le projet concerné, sans l'écrire avant ma validation.

Comparaison d’offres

Scrape les pages publiques de pricing de Firecrawl et d'Apify.
Compare uniquement les éléments explicitement publiés : prix, unité de facturation, engagement et fonctionnalités incluses.
Indique la date de consultation et les URL.
Ne déduis pas les remises ou conditions non publiées.

Lecture d’une documentation

Prépare un crawl de la documentation de Notion à partir de https://developers.notion.com/docs.
Limite le périmètre aux guides de démarrage et de sécurité, avec un maximum de 20 pages.
Liste d'abord les pages prévues et l'estimation de consommation.
Après validation, produis une synthèse des concepts utiles au projet d'intégration Notion.

Préparation d’une décision fournisseur

Recherche les pages officielles sur la sécurité, la confidentialité, les tarifs et la réversibilité de Firecrawl.
Construis un tableau : affirmation du fournisseur, preuve, date, URL, question ouverte.
Ne formule aucune recommandation tant que les quatre thèmes ne sont pas couverts.

8. Limites et règles de sécurité

Utiliser des pages publiques

Utilise Firecrawl sur des pages publiques accessibles sans authentification. Ne lui transmets pas :

• une URL privée contenant un token ;
• un lien temporaire de partage confidentiel ;
• une page d’administration ;
• un extranet client ;
• un document RH, financier ou juridique non public ;
• une instruction visant à contourner une restriction d’accès.

Respecte les droits applicables, les conditions d’utilisation du site et les limites techniques. Une page accessible dans un navigateur n’est pas automatiquement libre de réutilisation ou de republication.

Contrôler la dépense et le périmètre

Un Crawl mal borné peut parcourir beaucoup plus de pages que prévu. Indique toujours une limite, les chemins inclus ou exclus et, lorsque c’est utile, une profondeur maximale. Commence par Map ou une courte liste d’URL lorsque tu dois découvrir la structure d’un grand site.

Conserver la traçabilité

Une analyse web utile à une décision doit conserver :

• les URL consultées ;
• la date de consultation ;
• la distinction entre fait extrait et interprétation ;
• les limites de la recherche ;
• les points qui demandent une vérification humaine.

Ne copie pas automatiquement toutes les pages dans le Business Brain. Enregistre la synthèse utile, les sources et les décisions. Le contenu brut reste une ressource temporaire sauf besoin documentaire explicite.

Connexion limitée sans clé

La documentation Firecrawl propose un MCP distant sans clé à l’adresse https://mcp.firecrawl.dev/v2/mcp. Il est limité en débit et expose principalement Search, Scrape et Parse.

Ce mode peut servir à vérifier rapidement qu’OpenCode sait joindre le service ou à débloquer une démonstration non sensible. Il ne remplace pas le parcours authentifié lorsque tu dois disposer d’un compte, suivre ta consommation et utiliser une surface d’outils plus complète.

Si la création de compte est bloquée, demande à Connect Tool de proposer ce mode temporaire, d’expliquer sa portée et de prévoir son retrait lorsque la connexion authentifiée sera disponible.

Exercice guidé

1. Crée ton compte Firecrawl avec l’adresse retenue pour le pilote.
2. Vérifie le plan actif et ses limites.
3. Génère une clé dédiée au pilote.
4. Place-la directement dans ton gestionnaire de secrets sous FIRECRAWL_API_KEY.
5. Lance /connect-tool firecrawl sans partager la valeur de la clé.
6. Vérifie et valide le plan de modification proposé.
7. Relance OpenCode.
8. Réalise le test Scrape sur https://example.com.
9. Réalise une recherche sur une source officielle liée à ton activité.
10. Prépare un crawl de cinq pages maximum et fais valider son périmètre avant exécution.
11. Vérifie la consommation dans Firecrawl.
12. Demande à OpenCode d’expliquer comment désactiver le MCP, sans effectuer la désactivation.

Output attendu

Tu disposes de :

• un compte Firecrawl dont le propriétaire est identifié ;
• un plan et une limite de consommation connus ;
• une clé dédiée stockée dans le coffre, absente du vault et de la configuration ;
• un MCP Firecrawl visible dans OpenCode ;
• un test Scrape réussi ;
• une recherche avec URL sources ;
• un crawl de test borné et une consommation vérifiée ;
• une procédure connue pour désactiver le MCP et révoquer la clé.

Validation

Le cours est validé si tu peux montrer, sans exposer de secret :

• le nom du compte ou de l’espace Firecrawl utilisé ;
• le plan actif et son quota ;
• le nom FIRECRAWL_API_KEY dans le coffre avec sa valeur masquée ;
• la configuration du MCP avec le mécanisme d’injection ;
• le résultat du scrape de https://example.com ;
• une recherche contenant des liens vérifiables ;
• le périmètre et le nombre de pages d’un crawl limité ;
• l’endroit où la clé peut être révoquée.

La preuve transmise au formateur contient les résultats des trois tests et une capture masquée de la configuration. Elle ne contient ni clé, ni URL privée, ni donnée sensible.

Si ça bloque

Firecrawl n’apparaît pas dans OpenCode

Ferme complètement OpenCode, relance-le et vérifie la liste des MCP. Si le problème persiste, demande à Connect Tool d’inspecter la configuration active sans la modifier et sans afficher les variables d’environnement.

npx est introuvable ou le MCP ne démarre pas

Vérifie node --version et la présence de Node.js 22 ou d’une version ultérieure. Vérifie ensuite que npx est accessible au processus lancé par OpenCode. Ne retire pas op run pour contourner le problème.

Le message indique une authentification invalide

Vérifie le nom exact FIRECRAWL_API_KEY, l’Environment ID, le compte Firecrawl et l’état de la clé. Ne demande pas à OpenCode d’afficher la valeur. Si la clé peut avoir été exposée, révoque-la et crée-en une nouvelle.

Une limite de débit ou de crédits est atteinte

Arrête les nouveaux appels, consulte le tableau de bord et vérifie la consommation. Réduis le périmètre de la demande. Ne passe pas à un plan payant sans validation du responsable du budget.

Une page retourne peu ou pas de contenu

Vérifie que l’URL est publique et correcte. Certaines pages dépendent de JavaScript, bloquent l’extraction ou imposent des conditions d’accès. N’essaie pas de contourner une authentification ou une restriction. Utilise une autre source officielle ou collecte manuellement l’information autorisée.

Le résultat semble faux ou périmé

Ouvre l’URL source, vérifie la date et compare le passage original au résumé. Lance une seconde recherche avec une source primaire. Corrige la synthèse avant de l’enregistrer ou de prendre une décision.

Fallback manuel

Si le MCP authentifié ne peut pas être terminé pendant la session :

1. utilise temporairement le MCP sans clé uniquement sur une page publique et non sensible, si ce mode est disponible ;
2. sinon, ouvre la page dans ton navigateur et fournis son URL ou un extrait non sensible à analyser ;
3. documente le blocage technique ;
4. reporte le crawl et toute collecte volumineuse ;
5. reprends la connexion avec le responsable technique.

Le fallback permet de continuer une analyse ponctuelle. Il ne valide pas l’installation authentifiée de Firecrawl.

Ressources

• Firecrawl
• Firecrawl : clés API
• Firecrawl : tarifs
• Firecrawl MCP local
• Firecrawl MCP sans clé
• Firecrawl : outils MCP
• Gestionnaire de secrets et connexions sécurisées
• Bloc 2 - Installer le socle

Ce qu’il faut retenir

• Scrape lit une page connue, Search trouve des sources, Crawl parcourt plusieurs pages ; commence toujours par le plus borné des trois qui couvre le besoin.
• La clé Firecrawl vit dans le gestionnaire de secrets, injectée au lancement du MCP, jamais dans opencode.json ni dans une conversation.
• Un crawl doit toujours porter une limite explicite : chemins, profondeur, nombre de pages.
• Une analyse web utile conserve les URL, la date de consultation et distingue le fait de l’interprétation.
• Firecrawl ne garantit ni l’exactitude ni l’actualité d’une source ; recoupe les faits déterminants avant une décision.

À faire

• Crée ton compte Firecrawl et vérifie le plan actif.
• Génère une clé dédiée et place-la dans FIRECRAWL_API_KEY du gestionnaire de secrets.
• Lance /connect-tool firecrawl et valide le plan de configuration proposé.
• Réalise les tests Scrape, Search et Crawl limité décrits dans l’exercice guidé.
• Vérifie la consommation dans le tableau de bord Firecrawl.

Suivant : Connecter Playwright MCP