Notion MCP rate limit: conecte o Notion ao Claude e corrija erros

Você pede ao Claude para organizar quarenta anotações de reunião no Notion, e no meio do caminho ele para com uma mensagem sobre rate limit. Nada está quebrado. O Notion está fazendo o que qualquer serviço movimentado faz quando as requisições chegam mais rápido do que ele consegue atender: ele diz "espere", e um cliente educado espera. O problema é que um assistente de IA nem sempre é educado. Ele pode fazer uma busca, ler os resultados, fazer mais seis buscas e gastar o orçamento de um minuto inteiro em poucos segundos.

Este artigo mostra o Notion MCP rate limit pelos dois lados. Você vai ver como conectar o Notion ao Claude, o que os limites permitem de fato, como ler o erro quando ele aparece e quais hábitos impedem que ele volte. Os números abaixo vêm da própria documentação para desenvolvedores do Notion, então você pode conferir cada um deles.

💡 Resposta rápida: o servidor MCP hospedado do Notion fica em https://mcp.notion.com/mcp. Os limites da API do Notion valem para as suas ferramentas: 180 requisições por minuto na maioria dos planos, 600 nos planos Business e Enterprise, além de um teto mais apertado de 20 chamadas a cada 10 segundos para buscas e consultas de fontes de dados. Quando receber um 429, espere o tempo indicado em Retry-After e depois envie menos requisições, mas com mais conteúdo em cada uma.

O que é o Notion MCP rate limit

Um rate limit funciona como uma torneira, não como uma parede. O Notion dá a cada conexão uma quantidade fixa de água por minuto. Você pode abrir a válvula até o fim e gastar tudo de uma vez, ou deixar pingar de forma uniforme. Quando o copo esvazia, a torneira fecha até a janela reiniciar. O Model Context Protocol (MCP) não muda essa regra. Ele só muda quem segura a torneira. Com o MCP, quem a segura é um modelo de IA que decide sozinho quantas chamadas fazer.

Os números por trás do 429

Estes são os limites que importam, retirados da página de limites de requisições e da página de ferramentas compatíveis do Notion.

Dois detalhes são fáceis de perder. Primeiro, o orçamento por minuto é uma janela, então uma rajada de 180 chamadas nos primeiros dez segundos é permitida, mas a chamada 181 espera até a janela reiniciar. Segundo, os limites de busca e de consulta são separados e bem mais apertados. Vinte chamadas em 10 segundos equivalem a duas por segundo, abaixo da média de 3 por segundo do orçamento geral. Um assistente que faz buscas em loop chega a esse teto muito antes de encostar no geral.

💡 Dica: o Notion ajusta seus limites com o tempo. Trate a tabela como um retrato do momento e confira a página de limites de requisições antes de construir qualquer coisa que dependa de um número exato.

Por que o Claude atinge o limite rápido

Cada chamada de ferramenta que o Claude faz é uma requisição. Um prompt como "resuma tudo sobre o lançamento do Q3" parece uma única tarefa, mas se expande em uma cadeia: uma notion-search, várias chamadas notion-fetch para as páginas que ela devolve e, depois, mais buscas por páginas filhas e bancos de dados vinculados. Uma pessoa navegando pelo Notion faz uma requisição a cada poucos segundos. Um assistente que percorre um plano faz essas requisições uma após a outra.

Gatilhos comuns:

• Buscas amplas que retornam muitas páginas, e cada uma delas depois é buscada de novo
• Loops sobre bases de dados, como editar 50 linhas uma por uma
• Novas tentativas imediatas, quando o modelo repete uma requisição que falhou sem esperar
• Chamadas de ferramenta em paralelo, quando várias requisições saem no mesmo segundo
• Conversas longas que releem as mesmas páginas o tempo todo

O Notion amortece o primeiro golpe. O servidor MCP tenta uma chamada de novo sozinho quando a espera é de dois segundos ou menos. Qualquer espera maior devolve um erro na hora, e esse é o erro que você vê no chat.

Conecte o Notion ao Claude

A conexão leva alguns minutos e usa OAuth, então você nunca cola uma chave secreta em um arquivo de configuração. O Notion descreve o servidor MCP dele como um servidor remoto hospedado pelo próprio Notion, o que significa que não há nada para instalar na configuração padrão.

Configure o conector no Claude.ai

1. Abra o Claude no navegador ou no aplicativo para desktop e vá em Configurações, depois em Conectores.
2. Encontre o Notion no diretório de conectores e escolha Conectar.
3. Faça login no Notion quando a janela do OAuth abrir e escolha o workspace ao qual você quer que o Claude tenha acesso.
4. Aprove o acesso que o Notion lista na tela de consentimento.
5. Inicie um novo chat, ative o conector do Notion e peça ao Claude que encontre uma página pelo nome para confirmar que ele funciona.

💡 Dica: os nomes dos menus mudam conforme a Anthropic atualiza o aplicativo. Se não encontrar Conectores, procure uma área de integrações ou ferramentas dentro de Configurações.

Adicione no Claude Code

O Claude Code precisa de um único comando. A documentação do Notion recomenda o endereço Streamable HTTP:

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

Copiar prompt

Em seguida, execute /mcp dentro do Claude Code e conclua o fluxo OAuth no seu navegador. O Notion afirma que ainda não existe autorização não interativa, então um servidor sem interface não consegue concluir o login sozinho. A flag de escopo define quem recebe a conexão:

Clientes sem suporte remoto

Alguns clientes não conseguem falar diretamente com um servidor remoto. Para eles, o Notion indica a ponte mcp-remote com uma configuração STDIO. Existe um endereço SSE de reserva em https://mcp.notion.com/sse, mas o endereço Streamable HTTP é o recomendado. O Notion também considera obsoleto o servidor antigo de código aberto e não o mantém ativamente, então novas configurações devem usar o servidor hospedado. Se uma conexão falhar na autenticação, desconecte, conecte de novo e verifique se sua conta do Notion tem permissão no workspace.

Leia o erro antes de corrigir

A expressão "rate limit" recebe a culpa por mais do que merece. Ler a resposta real economiza uma hora de tentativa e erro.

Identifique rate_limited e Retry-After

Quando você ultrapassa o limite, a API do Notion responde com o status HTTP 429 e o código de erro rate_limited. A resposta traz um cabeçalho Retry-After com um número inteiro de segundos e repete esse valor em additional_data.retry_after para clientes que não conseguem ler cabeçalhos.

Pelo MCP, a mesma ideia chega em um formato mais amigável. Se a espera for de dois segundos ou menos, o servidor tenta uma vez por conta própria. Se for maior, a chamada da ferramenta falha na hora e devolve retry_after_seconds e rate_limit_reason. O Claude vê esses campos, e um bom prompt diz exatamente o que ele deve fazer com eles.

Limitadores de busca e de consulta

Os limites específicos de cada ferramenta são onde a maioria dos assistentes tropeça. notion-search e notion-query-data-sources permitem 20 chamadas a cada 10 segundos cada um. Um modelo que procura a página certa com buscas repetidas esgota isso em instantes, mesmo quando o orçamento geral por minuto está quase intacto. O campo rate_limit_reason é o primeiro lugar para olhar quando você precisa saber qual limite recusou a chamada.

Isso é mesmo um rate limit?

Vários problemas parecem limitação de requisições e não são. Identifique o sintoma antes de mudar qualquer coisa.

A página de limites do Notion restringe uma única carga a 1.000 elementos de bloco e 500 KB, com arrays de tipos de bloco (incluindo rich text) limitados a 100 elementos. O conteúdo de texto em uma propriedade chega a no máximo 2.000 caracteres. Uma colagem grande pode falhar por esses motivos e parecer uma limitação à primeira vista.

Corrija os erros de rate limit rapidamente

Envie menos requisições, mas maiores

A requisição mais barata é a que você nunca envia. Em vez de pedir ao Claude para editar quarenta linhas uma por uma, peça para ele montar a mudança completa de uma página e aplicá-la em uma única chamada de notion-update-page, respeitando os limites de 1.000 blocos e 500 KB por carga. Uma chamada que faz dez coisas conta como uma só requisição no orçamento.

Ações práticas:

• Agrupe as edições por página, para que cada uma seja tocada uma única vez
• Divida trabalhos grandes em lotes de 20 a 30 itens por mensagem no chat
• Crie o conteúdo em uma só passagem com notion-create-pages, em vez de adicionar blocos um a um

Controle o loop de busca

Buscar é o hábito mais caro, porque cada busca é seguida de leituras das páginas encontradas. Dê ao Claude endereços diretos sempre que tiver. Uma URL ou ID de página permite que ele chame notion-fetch imediatamente, sem busca nenhuma. Para trabalhar com bases de dados, uma chamada de notion-query-data-sources com filtro devolve as linhas que você precisa de uma vez, enquanto buscas repetidas trariam fragmentos e gastariam o limite de 20 chamadas a cada 10 segundos. Quando precisar mesmo buscar, peça uma consulta bem delimitada. notion-search aceita filtros por local, criador, data e status, e uma consulta estreita devolve menos páginas para buscar depois.

Prompts que evitam tempestades de novas tentativas

A melhor correção não custa nada: diga ao Claude como agir quando o Notion disser não. Cole um bloco como este no início de uma tarefa 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

A última linha é uma rede de segurança. Se o chat cair na página 22, você sabe exatamente de onde retomar e não paga duas vezes pelas mesmas páginas.

Saiba quando fazer upgrade

As conexões Business e Enterprise recebem 600 requisições por minuto, 3,3 vezes as 180 dos outros planos. Isso ajuda em automações pesadas. O Notion lista os limites de busca e de consulta separadamente, como 20 chamadas a cada 10 segundos, então um orçamento maior do plano não os eleva de forma óbvia. Corrija os hábitos primeiro e, se os números ainda não couberem, pague por mais margem. Chame notion-get-tool-access para ver quais ferramentas o plano do seu workspace disponibiliza.

Cinco erros que queimam seu orçamento

1. Pedir "tudo" em um só prompt, o que se transforma em centenas de buscas
2. Deixar o Claude tentar de novo imediatamente em vez de esperar o tempo indicado
3. Buscar páginas cuja URL você já tem
4. Rodar várias tarefas pesadas ao mesmo tempo, para que disputem o mesmo orçamento
5. Ignorar o texto do erro e enviar o mesmo prompt de novo

Escreva lógica de nova tentativa para scripts

Se você chama o Notion a partir dos seus próprios scripts, ao lado do Claude, ritmo vence pressa. O conselho do próprio Notion é manter a lógica de nova tentativa em um único lugar central, respeitar Retry-After, usar backoff exponencial com jitter, limitar os atrasos de espera de reserva a 30 segundos e restringir o número total de tentativas.

Backoff com 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

O jitter importa. Sem ele, dez workers que falharam juntos tentam de novo juntos e falham juntos outra vez. Uma variação aleatória de meio segundo os espalha.

Um alerta da documentação do Notion: se uma gravação retornar um 503, confira additional_data.retry_guidance antes de repeti-la, porque a alteração pode já ter sido salva. Novas tentativas cegas em gravações podem criar duplicatas.

Espace as requisições antes que falhem

O backoff reage à falha. O espaçamento evita a falha. Distribua as requisições de forma uniforme e fique perto de 80% do orçamento:

O Notion permite rajadas, então o espaçamento é opcional em tarefas curtas. Para execuções longas sem supervisão, ele faz a diferença entre um fim tranquilo e um muro de erros. Dê às chamadas de busca e de consulta um ritmo próprio, mais lento: uma chamada a cada 0,6 segundo, mais ou menos, mantém você abaixo de 20 a cada 10 segundos.

Use o Claude Sonnet 5 no PicassoIA

Quando o problema é código, um modelo de programação economiza tempo. O Claude Sonnet 5 no PicassoIA lê um erro, escreve uma correção e aceita capturas de tela como entrada. Para ser claro, ele redige scripts e prompts para você. Ele não se conecta sozinho ao seu workspace do Notion.

1. Abra a página do Claude Sonnet 5 no PicassoIA.
2. Cole o erro bruto em Prompt: a resposta 429, o valor de retry_after_seconds e uma frase sobre o que você estava fazendo.
3. Escolha um nível de Effort. O padrão, baixo, responde mais rápido. Escolha médio ou alto para lógica de nova tentativa que toque em vários arquivos.
4. Deixe Max Tokens em 8.192 para um wrapper completo de nova tentativa com explicação, ou reduza para respostas rápidas.
5. Adicione um System Prompt como "Você é um engenheiro de backend cuidadoso. Responda primeiro com o código e depois com uma explicação de três linhas."
6. Anexe uma captura de tela do erro no campo Image se o texto for difícil de copiar.
7. Execute, leia o resultado e teste o código com um lote pequeno antes de uma execução grande.

Para tarefas de programação mais difíceis, com várias etapas, o Claude Fable 5 está na mesma coleção de modelos de linguagem (LLM).

Crie suas próprias imagens no Picasso IA

Quando o seu workspace do Notion estiver funcionando bem, dê a ele visuais melhores. Uma boa imagem de cabeçalho transforma uma página de projeto, a página inicial de uma wiki ou um briefing de lançamento de um bloco de texto em algo que as pessoas querem abrir. O PicassoIA Image e o Seedream 5 Pro transformam um prompt de uma linha em uma imagem fotorrealista, e cada resultado está pronto para colocar em uma página do Notion.

Experimente um prompt neste formato: assunto, cenário, luz, lente. Por exemplo, "um gerente de projetos revisando roteiros impressos em uma mesa ensolarada, luz suave de janela, lente de 50mm, granulação natural de filme". Mude um detalhe por vez e você verá o que cada palavra faz.

Abra o Picasso IA, escolha um modelo e crie sua primeira imagem de cabeçalho hoje. Veja todos os modelos disponíveis em picassoia.com/en/all-models e continue experimentando até que suas páginas do Notion fiquem tão boas quanto funcionam.