Límite de tasa de Notion MCP: conecta Notion a Claude y corrige los errores

Le pides a Claude que ordene cuarenta notas de reunión en Notion y, a mitad de camino, se detiene con un mensaje sobre un límite de tasa. No se ha roto nada. Notion hace lo que hace cualquier servicio saturado cuando las peticiones llegan más rápido de lo que puede atender: dice "espera", y un cliente bien educado espera. El problema es que un asistente de IA no siempre es tan paciente. Puede lanzar una búsqueda, leer los resultados, lanzar seis búsquedas más y gastar un minuto entero de presupuesto en pocos segundos.

Este artículo repasa el Notion MCP rate limit desde los dos lados. Verás cómo conectar Notion a Claude, qué permiten realmente los límites, cómo leer el error cuando aparece y qué hábitos evitan que vuelva. Las cifras de abajo provienen de la propia documentación para desarrolladores de Notion, así que puedes comprobar cada una.

💡 Respuesta rápida: el servidor MCP alojado de Notion está en https://mcp.notion.com/mcp. Los límites de la API de Notion se aplican a sus herramientas: 180 solicitudes por minuto en la mayoría de los planes, 600 en Business y Enterprise, además de un tope más estricto de 20 llamadas cada 10 segundos en las búsquedas y las consultas de fuentes de datos. Cuando recibas un 429, espera el tiempo que marque Retry-After y luego envía menos solicitudes, pero más grandes.

Qué significa el Notion MCP rate limit

Un límite de tasa funciona como un grifo, no como un muro. Notion le asigna a cada conexión una cantidad fija de agua por minuto. Puedes abrir la válvula a tope y gastarlo todo de golpe, o dejarlo gotear de forma uniforme. Cuando el vaso está vacío, el grifo se cierra hasta que la ventana se reinicia. El Model Context Protocol (MCP) no cambia esa regla. Solo cambia quién sostiene el grifo. Con MCP, quien lo sostiene es un modelo de IA que decide por su cuenta cuántas llamadas hacer.

Las cifras detrás del 429

Estos son los límites que importan, tomados de la página de límites de solicitudes de Notion y de su página de herramientas compatibles.

Dos detalles son fáciles de pasar por alto. Primero, el presupuesto por minuto es una ventana, así que una ráfaga de 180 llamadas en los primeros diez segundos está permitida, pero la llamada 181 espera a que la ventana se reinicie. Segundo, los topes de búsqueda y consulta son independientes y mucho más estrictos. Veinte llamadas en 10 segundos son dos por segundo, lo que queda por debajo de la media de 3 por segundo del presupuesto general. Un asistente que busca en bucle llega a ese techo mucho antes de tocar el límite general.

💡 Consejo: Notion ajusta sus límites con el tiempo. Trata la tabla como una foto fija y revisa la página de límites de solicitudes antes de construir algo que dependa de una cifra exacta.

Por qué Claude alcanza el límite tan rápido

Cada llamada a una herramienta que hace Claude es una sola solicitud. Un prompt como "resume todo sobre el lanzamiento del Q3" parece una tarea única, pero se expande en una cadena: una notion-search, varias llamadas notion-fetch para las páginas que devuelve, y luego más consultas para las subpáginas y las bases de datos vinculadas. Una persona que navega por Notion hace una solicitud cada pocos segundos. Un asistente que sigue un plan las hace una tras otra.

Desencadenantes habituales:

• Búsquedas amplias que devuelven muchas páginas, cada una de las cuales se lee después
• Bucles sobre bases de datos, como editar 50 filas una a una
• Reintentos instantáneos, cuando el modelo repite una solicitud fallida sin esperar
• Llamadas paralelas a herramientas, cuando varias solicitudes salen en el mismo segundo
• Chats largos que releen una y otra vez las mismas páginas

Notion amortigua el primer golpe. El servidor MCP reintenta una llamada una vez por su cuenta cuando la espera es de dos segundos o menos. Todo lo que tarde más devuelve un error de inmediato, y ese es el error que ves en el chat.

Conecta Notion a Claude

Conectar lleva unos minutos y usa OAuth, así que nunca pegas un secreto en un archivo de configuración. Notion describe su servidor MCP como un servidor remoto alojado por Notion, lo que significa que, para la configuración estándar, no hay nada que instalar.

Configura el conector de Claude.ai

1. Abre Claude en tu navegador o en la aplicación de escritorio y ve a Settings, luego a Connectors.
2. Busca Notion en el directorio de conectores y elige Connect.
3. Inicia sesión en Notion cuando se abra la ventana de OAuth y elige el espacio de trabajo al que quieres que Claude acceda.
4. Aprueba el acceso que Notion indica en la pantalla de consentimiento.
5. Empieza un chat nuevo, activa el conector de Notion y pídele a Claude que busque una página por su nombre para confirmar que funciona.

💡 Consejo: Los nombres de los menús cambian a medida que Anthropic actualiza la app. Si no encuentras Connectors, busca un área de integraciones o herramientas dentro de Settings.

Añádelo en Claude Code

Claude Code necesita un solo comando. La documentación de Notion recomienda la dirección Streamable HTTP:

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

Copiar prompt

A continuación, ejecuta /mcp dentro de Claude Code y completa el flujo de OAuth en tu navegador. Notion indica que todavía no existe una autorización no interactiva, así que un servidor sin interfaz gráfica no puede completar el inicio de sesión por sí solo. El indicador de ámbito decide quién obtiene la conexión:

Clientes sin compatibilidad remota

Algunos clientes no pueden comunicarse directamente con un servidor remoto. Para ellos, Notion apunta al puente mcp-remote con una configuración STDIO. Existe una dirección SSE de respaldo en https://mcp.notion.com/sse, pero la dirección Streamable HTTP es la recomendada. Notion también considera obsoleto su antiguo servidor de código abierto y no lo mantiene activamente, así que las configuraciones nuevas deben usar el servidor alojado. Si una conexión falla al autenticarse, desconéctala, vuelve a conectarla y comprueba que tu cuenta de Notion tiene permiso en el espacio de trabajo.

Lee el error antes de corregirlo

Se culpa a "rate limit" de más de lo que merece. Leer la respuesta real te ahorra una hora de conjeturas.

Identifica rate_limited y Retry-After

Cuando superas el límite, la API de Notion responde con el estado HTTP 429 y el código de error rate_limited. La respuesta incluye un encabezado Retry-After con un número entero de segundos, y repite ese valor en additional_data.retry_after para los clientes que no pueden leer encabezados.

A través de MCP, la misma idea llega con una forma más amigable. Si la espera es de dos segundos o menos, el servidor reintenta una vez por su cuenta. Si es más larga, la llamada a la herramienta falla de inmediato y devuelve retry_after_seconds y rate_limit_reason. Claude ve esos campos, y un buen prompt le indica exactamente qué hacer con ellos.

Limitaciones de búsqueda y consulta

Los topes específicos de cada herramienta son los que más hacen tropezar a la mayoría de los asistentes. notion-search y notion-query-data-sources permiten cada uno 20 llamadas cada 10 segundos. Un modelo que busca la página correcta con búsquedas repetidas lo agota en un momento, incluso cuando el presupuesto general por minuto está casi intacto. El campo rate_limit_reason es el primer lugar donde mirar cuando necesitas saber qué límite rechazó la llamada.

¿Es realmente un límite de tasa?

Varios problemas parecen un límite de tasa y no lo son. Identifica el síntoma antes de cambiar nada.

La página de límites de Notion restringe una sola carga a 1.000 elementos de bloque y 500 KB, y los arrays de tipos de bloque (incluido el texto enriquecido) a 100 elementos. El contenido de texto de una propiedad llega como máximo a 2.000 caracteres. Un pegado grande puede fallar por esos motivos y, a primera vista, parecer un límite de tasa.

Corrige rápido los errores de límite de tasa

Envía menos solicitudes, pero más grandes

La solicitud más barata es la que nunca envías. En lugar de pedirle a Claude que edite cuarenta filas una a una, pídele que prepare el cambio completo de una página y lo aplique en una sola llamada a notion-update-page, sin superar los límites de carga de 1.000 bloques y 500 KB. Una llamada que hace diez cosas cuenta como una sola solicitud contra el presupuesto.

Movimientos prácticos:

• Agrupa las ediciones por página, para tocar cada una una sola vez
• Divide los trabajos grandes en lotes de 20 a 30 elementos por mensaje del chat
• Crea el contenido de una vez con notion-create-pages en lugar de añadir bloques uno a uno

Controla el bucle de búsqueda

Buscar es el hábito más caro, porque cada búsqueda va seguida de lecturas. Dale a Claude direcciones directas siempre que las tengas. Una URL o un ID de página le permite llamar a notion-fetch de inmediato, sin buscar nada. Para trabajar con bases de datos, una llamada filtrada a notion-query-data-sources devuelve de una vez las filas que necesitas, mientras que las búsquedas repetidas devolverían fragmentos y agotarían el tope de 20 llamadas cada 10 segundos. Cuando sí necesites buscar, pide una sola consulta bien acotada. notion-search admite filtros por ubicación, creador, fecha y estado, y una consulta precisa devuelve menos páginas que leer después.

Prompts que frenan las avalanchas de reintentos

La mejor solución no cuesta nada: dile a Claude cómo debe actuar cuando Notion diga que no. Pega un bloque como este al inicio de una tarea grande:

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.

Copiar prompt

La última línea es una red de seguridad. Si el chat se corta en la página 22, sabes exactamente dónde retomar y no gastas dos veces en las mismas páginas.

Cuándo conviene mejorar el plan

Las conexiones de Business y Enterprise reciben 600 solicitudes por minuto, 3,3 veces las 180 de los demás planes. Eso ayuda en automatizaciones intensas. Notion enumera los topes de búsqueda y consulta por separado, como 20 llamadas cada 10 segundos, así que un presupuesto mayor del plan no los eleva de forma evidente. Corrige primero los hábitos y, si las cifras siguen sin encajar, mejora el plan para tener más margen. Llama a notion-get-tool-access para ver qué herramientas incluye el plan de tu espacio de trabajo.

Cinco errores que agotan tu presupuesto

1. Pedir "todo" en un solo prompt, lo que se convierte en cientos de lecturas
2. Dejar que Claude reintente al instante en lugar de esperar el tiempo indicado
3. Buscar páginas de las que ya tienes la URL
4. Ejecutar varias tareas pesadas a la vez, de modo que compiten por el mismo presupuesto
5. Ignorar el texto del error y enviar el mismo prompt otra vez

Escribe la lógica de reintentos para tus scripts

Si llamas a Notion desde tus propios scripts junto a Claude, el ritmo vence a la prisa. El propio consejo de Notion es mantener la lógica de reintentos en un solo lugar, respetar Retry-After, usar retroceso exponencial con jitter (variación aleatoria), limitar los retrasos de respaldo a 30 segundos y acotar el número total de intentos.

Retroceso exponencial con 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")

Copiar prompt

El jitter importa. Sin él, diez procesos que fallaron juntos reintentan juntos y vuelven a fallar juntos. Una variación aleatoria de medio segundo los separa.

Una advertencia de la documentación de Notion: si una escritura devuelve un 503, revisa additional_data.retry_guidance antes de repetirla, porque el cambio puede estar ya guardado. Los reintentos a ciegas en escrituras pueden crear duplicados.

Regula las solicitudes antes de que fallen

El retroceso reacciona al fallo. Regular el ritmo lo evita. Reparte las solicitudes de forma uniforme y mantente cerca del 80 por ciento del presupuesto:

Notion permite ráfagas, así que regular el ritmo es opcional en trabajos cortos. En ejecuciones largas sin supervisión, es la diferencia entre terminar sin problemas y un muro de errores. Dale a las llamadas de búsqueda y consulta un ritmo propio, más lento: una llamada cada 0,6 segundos más o menos te mantiene por debajo de 20 cada 10 segundos.

Usa Claude Sonnet 5 en PicassoIA

Cuando el problema es de código, un modelo de programación ahorra tiempo. Claude Sonnet 5 en PicassoIA lee un error, escribe una corrección y acepta capturas de pantalla como entrada. Para que quede claro: redacta scripts y prompts por ti. No se conecta por sí mismo a tu espacio de trabajo de Notion.

1. Abre la página de Claude Sonnet 5 en PicassoIA.
2. Pega el error sin procesar en Prompt: la respuesta 429, el valor de retry_after_seconds y una frase sobre lo que estabas haciendo.
3. Elige un nivel de Effort. El predeterminado, low, responde más rápido. Elige medium o high para la lógica de reintentos que afecte a varios archivos.
4. Deja Max Tokens en 8.192 para un envoltorio de reintentos completo con explicación, o bájalo para respuestas rápidas.
5. Añade un System Prompt como "Eres un ingeniero de backend cuidadoso. Responde primero con el código y luego con una explicación de tres líneas."
6. Adjunta una captura del error en el campo Image si el texto es difícil de copiar.
7. Ejecútalo, lee el resultado y prueba el código con un lote pequeño antes de una ejecución grande.

Para trabajos de programación más difíciles y de varios pasos, Claude Fable 5 está en la misma colección de modelos de lenguaje (LLM).

Crea tus propias imágenes en Picasso IA

Cuando tu espacio de trabajo de Notion funcione bien, dale mejores imágenes. Una buena imagen de cabecera convierte una página de proyecto, la portada de una wiki o un resumen de lanzamiento de un muro de texto en algo que la gente quiere abrir. PicassoIA Image y Seedream 5 Pro convierten un prompt de una sola línea en una imagen fotorrealista, y cada resultado está listo para insertarse en una página de Notion.

Prueba un prompt con esta forma: sujeto, escenario, luz, objetivo. Por ejemplo, "un jefe de proyecto revisando hojas de ruta impresas en una mesa iluminada por el sol, luz suave de ventana, objetivo de 50 mm, grano de película natural". Cambia un detalle a la vez y verás lo que hace cada palabra.

Abre Picasso IA, elige un modelo y crea hoy tu primera imagen de cabecera. Explora todos los modelos disponibles en picassoia.com/en/all-models y sigue experimentando hasta que tus páginas de Notion se vean tan bien como funcionan.