Limite de débit Notion MCP : connecter Notion à Claude et corriger les erreurs

Vous demandez à Claude de ranger quarante comptes rendus de réunion dans Notion, et à mi-parcours il s’arrête avec un message sur une limite de débit. Rien n’est cassé. Notion fait ce que fait tout service sollicité : lorsque les requêtes arrivent plus vite qu’il ne peut les traiter, il dit « attendez », et un client bien élevé attend. Le problème, c’est qu’un assistant d’IA n’est pas toujours bien élevé. Il peut lancer une recherche, lire les résultats, en lancer six autres, et consommer une minute entière de budget en quelques secondes.

Cet article détaille la limite de débit Notion MCP sous les deux angles. Vous verrez comment connecter Notion à Claude, ce que les limites permettent réellement, comment lire l’erreur quand elle apparaît, et quelles habitudes l’empêchent de revenir. Les chiffres ci-dessous proviennent de la documentation officielle pour développeurs de Notion, vous pouvez donc les vérifier un par un.

💡 Réponse rapide : le serveur MCP hébergé de Notion se trouve à https://mcp.notion.com/mcp. Les limites de l’API de Notion s’appliquent à ses outils : 180 requêtes par minute pour la plupart des forfaits, 600 pour Business et Enterprise, plus un plafond plus strict de 20 appels toutes les 10 secondes pour les recherches et les requêtes de sources de données. Quand vous obtenez un 429, attendez le temps indiqué par Retry-After, puis envoyez moins de requêtes, mais de plus grande taille.

Ce que signifie la limite de débit Notion MCP

Une limite de débit fonctionne comme un robinet, pas comme un mur. Notion alloue à chaque connexion une quantité d’eau fixe par minute. Vous pouvez ouvrir la vanne en grand et tout dépenser d’un coup, ou laisser couler goutte à goutte. Quand le récipient est vide, le robinet se referme jusqu’à la réinitialisation de la fenêtre. Le Model Context Protocol (MCP) ne change pas cette règle. Il change seulement la personne qui tient le robinet. Avec MCP, celui qui le tient est un modèle d’IA qui décide seul du nombre d’appels à effectuer.

Les chiffres derrière l’erreur 429

Voici les limites qui comptent, tirées de la page des limites de requêtes de Notion et de sa page des outils pris en charge.

Deux détails passent facilement inaperçus. D’abord, le budget par minute est une fenêtre : une rafale de 180 appels dans les dix premières secondes est autorisée, mais l’appel 181 attend la réinitialisation de la fenêtre. Ensuite, les plafonds de recherche et de requête sont distincts et beaucoup plus serrés. Vingt appels en 10 secondes représentent deux par seconde, soit moins que la moyenne de 3 par seconde du budget général. Un assistant qui effectue des recherches en boucle atteint ce plafond bien avant de toucher au plafond général.

💡 Astuce : Notion ajuste ses limites au fil du temps. Considérez le tableau comme un instantané et vérifiez la page des limites de requêtes avant de construire quoi que ce soit qui dépende d’un chiffre exact.

Pourquoi Claude atteint la limite si vite

Chaque appel d’outil effectué par Claude correspond à une requête. Un prompt comme « résume tout ce qui concerne le lancement du T3 » semble être une tâche unique, mais il se transforme en chaîne : un notion-search, puis plusieurs appels notion-fetch pour les pages renvoyées, puis d’autres récupérations pour les sous-pages et les bases de données liées. Une personne qui navigue dans Notion envoie une requête toutes les quelques secondes. Un assistant qui travaille sur un plan les enchaîne sans pause.

Déclencheurs fréquents :

• Recherches larges qui renvoient de nombreuses pages, chacune devant ensuite être récupérée
• Boucles sur des bases de données, par exemple modifier 50 lignes une par une
• Relances instantanées, lorsque le modèle répète une requête échouée sans attendre
• Appels d’outils en parallèle, quand plusieurs requêtes partent dans la même seconde
• Longues conversations qui relisent sans cesse les mêmes pages

Notion amortit le premier choc. Le serveur MCP relance un appel une seule fois de lui-même lorsque l’attente est de deux secondes ou moins. Au-delà, l’erreur est renvoyée immédiatement, et c’est celle que vous voyez dans la conversation.

Connecter Notion à Claude

La connexion prend quelques minutes et utilise OAuth, si bien que vous ne collez jamais de secret dans un fichier de configuration. Notion décrit son serveur MCP comme un serveur distant hébergé par Notion, ce qui signifie qu’il n’y a rien à installer pour la configuration standard.

Configurer le connecteur Claude.ai

1. Ouvrez Claude dans votre navigateur ou dans l’application de bureau, puis allez dans Paramètres, puis Connecteurs.
2. Trouvez Notion dans le répertoire des connecteurs et choisissez Connecter.
3. Connectez-vous à Notion lorsque la fenêtre OAuth s’ouvre et sélectionnez l’espace de travail auquel vous voulez que Claude accède.
4. Approuvez les accès que Notion indique sur l’écran de consentement.
5. Lancez une nouvelle conversation, activez le connecteur Notion et demandez à Claude de trouver une page par son nom pour vérifier que tout fonctionne.

💡 Astuce : Les noms des menus changent au fil des mises à jour d’Anthropic. Si vous ne trouvez pas Connecteurs, cherchez une zone intitulée intégrations ou outils dans les Paramètres.

L’ajouter dans Claude Code

Claude Code n’a besoin que d’une commande. La documentation de Notion recommande l’adresse Streamable HTTP :

claude mcp add --transport http notion https://mcp.notion.com/mcp

Copier le prompt

Ensuite, exécutez /mcp dans Claude Code et terminez le flux OAuth dans votre navigateur. Notion indique qu’il n’existe pas encore d’autorisation non interactive, donc un serveur sans interface ne peut pas finaliser la connexion seul. L’option de portée détermine qui bénéficie de la connexion :

Clients sans prise en charge du distant

Certains clients ne peuvent pas communiquer directement avec un serveur distant. Pour ceux-là, Notion renvoie vers le pont mcp-remote avec une configuration STDIO. Une adresse SSE de secours existe à https://mcp.notion.com/sse, mais l’adresse Streamable HTTP est celle recommandée. Notion qualifie aussi son ancien serveur open source de déprécié et ne l’entretient plus activement, donc les nouvelles configurations doivent passer par le serveur hébergé. Si une connexion échoue à l’authentification, déconnectez-la, reconnectez-la et vérifiez que votre compte Notion a bien les droits sur l’espace de travail.

Lire l’erreur avant de la corriger

La mention « limite de débit » est tenue pour responsable de bien plus que ce qu’elle mérite. Lire la réponse réelle évite une heure de devinettes.

Repérer rate_limited et Retry-After

Quand vous dépassez la limite, l’API de Notion répond avec le statut HTTP 429 et le code d’erreur rate_limited. La réponse contient un en-tête Retry-After avec un nombre entier de secondes, et répète cette valeur dans additional_data.retry_after pour les clients qui ne peuvent pas lire les en-têtes.

Via MCP, la même logique arrive sous une forme plus lisible. Si l’attente est de deux secondes ou moins, le serveur relance une fois par lui-même. Si elle est plus longue, l’appel d’outil échoue aussitôt et renvoie retry_after_seconds et rate_limit_reason. Claude voit ces champs, et un bon prompt lui indique exactement quoi en faire.

Limitations des recherches et des requêtes

Les plafonds propres à chaque outil sont là où la plupart des assistants trébuchent. notion-search et notion-query-data-sources autorisent chacun 20 appels toutes les 10 secondes. Un modèle qui cherche la bonne page par des recherches répétées épuise ce quota en un instant, même si le budget général par minute est presque intact. Le champ rate_limit_reason est le premier endroit où regarder lorsque vous voulez savoir quelle limite a refusé l’appel.

S’agit-il vraiment d’une limite de débit ?

Plusieurs problèmes ressemblent à une limitation de débit sans en être une. Identifiez le symptôme avant de modifier quoi que ce soit.

La page des limites de Notion plafonne une charge utile unique à 1 000 éléments de bloc et 500 Ko, les tableaux de types de blocs (y compris le texte enrichi) étant limités à 100 éléments. Le contenu texte d’une propriété ne dépasse pas 2 000 caractères. Un collage volumineux peut échouer pour ces raisons et ressembler à une limitation au premier coup d’œil.

Corriger vite les erreurs de limite de débit

Envoyer moins de requêtes, mais plus grosses

La requête la moins coûteuse est celle que vous n’envoyez jamais. Au lieu de demander à Claude de modifier quarante lignes une par une, demandez-lui de préparer la modification complète d’une page et de l’appliquer en un seul appel notion-update-page, en restant sous les limites de 1 000 blocs et de 500 Ko par charge utile. Un appel qui fait dix choses ne compte que pour une requête dans le budget.

Actions concrètes :

• Regroupez les modifications par page, pour que chaque page ne soit touchée qu’une fois
• Découpez les gros travaux en lots de 20 à 30 éléments par message de conversation
• Créez le contenu en une seule passe avec notion-create-pages, plutôt que d’ajouter les blocs un par un

Maîtriser la boucle de recherche

La recherche est l’habitude la plus coûteuse, car chaque recherche est suivie de récupérations. Donnez à Claude des adresses directes chaque fois que vous en avez. Une URL ou un identifiant de page lui permet d’appeler notion-fetch tout de suite, sans aucune recherche. Pour le travail sur les bases de données, un appel notion-query-data-sources filtré renvoie les lignes voulues d’un seul coup, là où des recherches répétées ne renverraient que des fragments et consommeraient le plafond de 20 appels toutes les 10 secondes. Quand vous devez vraiment chercher, demandez une requête unique et bien délimitée. notion-search prend en charge des filtres sur le lieu, l’auteur, la date et le statut, et une requête précise renvoie moins de pages à récupérer ensuite.

Des prompts qui évitent les tempêtes de relances

La meilleure correction ne coûte rien : indiquez à Claude comment se comporter quand Notion dit non. Collez un bloc de ce type au début d’une grande tâche :

Update the 30 pages in the "Meeting Notes" database one at a time.
Use notion-fetch with the page URL instead of searching for each page.
Run one Notion call at a time. If a call returns a rate limit error,
wait the number of seconds in retry_after_seconds, then continue from the same page.
After every 10 pages, tell me which pages are finished and which are left.

Copier le prompt

La dernière ligne est un filet de sécurité. Si la conversation s’interrompt à la page 22, vous savez exactement où reprendre, et vous ne payez pas deux fois les mêmes pages.

Savoir quand passer à un forfait supérieur

Les connexions Business et Enterprise reçoivent 600 requêtes par minute, soit 3,3 fois les 180 des autres forfaits. Cela aide pour l’automatisation intensive. Notion liste séparément les plafonds de recherche et de requête, à 20 appels toutes les 10 secondes, si bien qu’un budget de forfait plus élevé ne les relève pas forcément. Corrigez d’abord les habitudes, puis payez pour de la marge si les chiffres ne suffisent toujours pas. Appelez notion-get-tool-access pour voir quels outils votre forfait d’espace de travail rend disponibles.

Cinq erreurs qui épuisent votre budget

1. Demander « tout » dans un seul prompt, ce qui se transforme en centaines de récupérations
2. Laisser Claude relancer instantanément au lieu d’attendre le délai indiqué
3. Chercher des pages dont vous avez déjà l’URL
4. Lancer plusieurs tâches lourdes en même temps, qui se disputent le même budget
5. Ignorer le texte de l’erreur, puis renvoyer le même prompt

Écrire la logique de relance pour vos scripts

Si vous appelez Notion depuis vos propres scripts en plus de Claude, le rythme l’emporte sur la précipitation. Le conseil de Notion est de centraliser la logique de relance à un seul endroit, de respecter Retry-After, d’utiliser un backoff exponentiel avec jitter, de plafonner les délais de repli à 30 secondes et de limiter le nombre total de tentatives.

Backoff avec jitter

import random
import time

import requests


def notion_request(method, url, headers, max_attempts=5, **kwargs):
    for attempt in range(max_attempts):
        response = requests.request(method, url, headers=headers, **kwargs)
        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        if retry_after:
            wait = int(retry_after)
        else:
            wait = min(2 ** attempt, 30)

        time.sleep(wait + random.uniform(0, 0.5))

    raise RuntimeError("Still rate limited after all attempts")

Copier le prompt

Le jitter compte. Sans lui, dix workers qui ont échoué ensemble relancent ensemble et échouent de nouveau ensemble. Une demi-seconde aléatoire les répartit.

Un avertissement issu de la documentation de Notion : si une écriture renvoie un 503, vérifiez additional_data.retry_guidance avant de la répéter, car la modification a peut-être déjà été enregistrée. Les relances aveugles sur les écritures peuvent créer des doublons.

Cadencer les requêtes avant qu’elles échouent

Le backoff réagit à l’échec. Le cadencement l’évite. Répartissez les requêtes régulièrement et restez proche de 80 % du budget :

Notion autorise les rafales, donc le cadencement est facultatif pour les courts travaux. Pour les longues exécutions sans surveillance, c’est la différence entre une fin fluide et un mur d’erreurs. Donnez aux appels de recherche et de requête un rythme plus lent qui leur est propre : un appel toutes les 0,6 seconde environ vous maintient sous 20 par 10 secondes.

Utiliser Claude Sonnet 5 sur PicassoIA

Quand le problème vient du code, un modèle spécialisé fait gagner du temps. Claude Sonnet 5 sur PicassoIA lit une erreur, rédige une correction et accepte des captures d’écran en entrée. Pour être clair, il rédige des scripts et des prompts à votre place. Il ne se connecte pas lui-même à votre espace de travail Notion.

1. Ouvrez la page de Claude Sonnet 5 sur PicassoIA.
2. Collez l’erreur brute dans Prompt : la réponse 429, la valeur retry_after_seconds, et une phrase sur ce que vous faisiez.
3. Choisissez un niveau d’Effort. La valeur par défaut, low, répond le plus vite. Choisissez medium ou high pour une logique de relance qui touche plusieurs fichiers.
4. Laissez Max Tokens à 8 192 pour un wrapper de relance complet avec une explication, ou baissez-le pour des réponses rapides.
5. Ajoutez un System Prompt du type « Vous êtes un ingénieur back-end rigoureux. Répondez d’abord par le code, puis par une explication de trois lignes ».
6. Joignez une capture d’écran de l’erreur dans le champ Image si le texte est difficile à copier.
7. Lancez, lisez le résultat et testez le code sur un petit lot avant une grande exécution.

Pour les travaux de code plus ardus en plusieurs étapes, Claude Fable 5 figure dans la même collection Large Language Models.

Créer vos propres images sur PicassoIA

Une fois votre espace de travail Notion bien rodé, donnez-lui de meilleurs visuels. Une belle image d’en-tête fait passer une page de projet, l’accueil d’un wiki ou un brief de lancement d’un mur de texte à quelque chose que l’on a envie d’ouvrir. PicassoIA Image et Seedream 5 Pro transforment un prompt d’une seule ligne en image photoréaliste, et chaque résultat est prêt à être déposé dans une page Notion.

Essayez un prompt de cette forme : sujet, décor, lumière, objectif. Par exemple, « une cheffe de projet qui relit des feuilles de route imprimées à une table ensoleillée, lumière douce de fenêtre, objectif 50 mm, grain de film naturel ». Changez un seul détail à la fois, et vous verrez ce que fait chaque mot.

Ouvrez PicassoIA, choisissez un modèle et créez dès aujourd’hui votre première image d’en-tête. Parcourez tous les modèles disponibles sur picassoia.com/en/all-models, et continuez d’expérimenter jusqu’à ce que vos pages Notion soient aussi belles qu’elles fonctionnent bien.