Uma lista que cabe em uma resposta não é necessariamente uma lista completa. Se uma tool MCP devolve apenas os primeiros registros e não informa que há mais dados, o agente pode responder com segurança aparente a partir de uma amostra. Se ela devolve tudo, o custo da chamada cresce justamente quando o conjunto deixa de caber bem no contexto.
A solução é tratar paginação como parte do contrato da tool: devolva uma página limitada, uma ordem estável, um cursor opaco e um sinal explícito de completude. O agente continua somente quando ainda há uma razão para buscar mais. Antes de expor a tool pela rede, o servidor MCP remoto em TypeScript com HTTP ajuda a separar transporte, autenticação e execução. Este artigo trata de outra fronteira: o que a própria resposta de busca promete.
O código abaixo é uma fixture local em Node.js. Ela não chama um modelo nem um servidor MCP real. O objetivo é provar a política de paginação, não medir desempenho de um provedor.
Regra de projeto
- Uma página é um pedaço do resultado, não uma resposta completa.
- O cursor deve ser opaco para o cliente e válido somente para a consulta e o snapshot que o servidor controla.
- A resposta precisa dizer se ainda há dados, sem obrigar o modelo a deduzir isso pelo tamanho da lista.
- Filtrar no servidor, agregar ou gerar um arquivo pode ser melhor do que paginar milhares de linhas através do contexto.
O problema está no significado, não no tamanho
O erro mais perigoso não é uma resposta grande demais. É uma resposta parcial que parece final. Um campo items com dez registros não diz se existem dez registros no total, se o servidor aplicou um limite, ou se a consulta encontrou exatamente aquele conjunto.
Esse significado também não deve ficar escondido em uma instrução vaga na descrição da tool. O runtime precisa conseguir registrar se a resposta estava completa e o agente precisa receber essa informação junto dos dados. Se a consulta for usada para responder "quais são todos os pedidos atrasados?", o resultado deve carregar a condição que permite ou impede essa conclusão.
Há um segundo risco: deixar o modelo decidir sozinho quantas páginas ler. Sem limite por execução, a tool pode consumir chamadas repetidas para atravessar um conjunto que deveria ter sido filtrado no servidor. O detector de tool call repetida e polling legítimo resolve outro problema, mas a mesma ideia vale aqui: o runtime deve conhecer a condição de parada.
Não confunda a paginação do protocolo com a paginação dos resultados
O MCP já possui paginação para operações de lista do protocolo. A documentação do cliente TypeScript mostra listTools() seguindo nextCursor para agregar páginas de ferramentas e também permite acessar uma página específica com um cursor guardado (MCP TypeScript SDK, "client calling", consultado em 20/11/2026). Isso resolve a descoberta de tools, prompts, resources e templates.
Esse mecanismo não transforma automaticamente o retorno de uma chamada de negócio em uma coleção navegável. Uma tool como search_orders ainda precisa definir o próprio formato de página, o significado do cursor, a ordem dos registros e a política para continuar. Misturar os dois contratos leva a uma suposição perigosa: a existência de nextCursor em tools/list não garante que tools/call saiba entregar o restante de search_orders.
Se a implementação usa a versão atual do SDK TypeScript, structuredContent e outputSchema podem tornar o contrato de saída explícito para a aplicação e para o cliente (MCP TypeScript SDK, "server API", consultado em 20/11/2026). Ainda assim, o schema não decide se a primeira página é suficiente. Ele só torna a decisão representável e verificável.
O que uma página de resultados precisa carregar?
Comece com um envelope pequeno. Os nomes podem variar, mas a semântica precisa ser estável:
| Campo | Responsabilidade |
|---|---|
items |
Registros desta página, já limitados ao orçamento da tool. |
nextCursor |
Token opaco para pedir a próxima página; ausente quando não há continuação. |
complete |
true somente quando o servidor sabe que a consulta terminou neste snapshot. |
snapshot |
Identificador ou versão usada para manter a consulta consistente, quando necessário. |
notice |
Texto curto para o modelo, especialmente quando a resposta está incompleta ou exige filtro. |
complete parece redundante com nextCursor, mas torna a intenção legível. O cursor pode expirar, ser rejeitado ou ser omitido por uma camada intermediária. O chamador não deveria declarar "todos" apenas porque recebeu uma lista com menos itens que o limite.
Não retorne total por hábito. Um total exato pode exigir uma consulta cara, envelhecer antes da próxima página ou sugerir uma precisão que o backend não garante. Se o total for necessário para a decisão, documente quando ele é calculado e qual snapshot ele representa.
Como manter o cursor seguro e estável?
O cursor não é um número de página para o agente interpretar. Ele é um recibo de continuação emitido pelo servidor. Pode carregar a versão do snapshot, a última chave ordenada e uma assinatura. O cliente deve apenas devolvê-lo.
Três regras evitam a maior parte dos problemas:
- Ordene de forma determinística. Uma consulta que alterna a ordem entre chamadas pode repetir registros ou pular itens.
- Valide o cursor no servidor. Rejeite tokens malformados, de outra consulta ou de um snapshot incompatível. Não aceite um
offsetenviado livremente quando isso permite atravessar dados fora do escopo. - Defina a vida útil. Um cursor pode expirar quando o snapshot deixa de existir. A resposta deve indicar que a consulta precisa recomeçar, em vez de continuar a partir de uma posição que já não representa o mesmo conjunto.
O cursor pode ser codificado em Base64URL para transporte, mas codificação não é autenticação. Se a posição revelar dados sensíveis ou puder ser alterada para acessar outro tenant, assine o conteúdo ou guarde o estado no servidor com uma referência aleatória.
Fixture Node.js: página, cursor e completude
A fixture abaixo usa uma lista fixa para deixar a verificação reproduzível. Em produção, substitua orders por uma consulta que tenha uma ordenação estável e defina como o snapshot será mantido. O cursor continua sendo um detalhe do servidor.
import assert from "node:assert/strict";
const orders = [
{ id: "ord-101", status: "late" },
{ id: "ord-102", status: "paid" },
{ id: "ord-103", status: "late" },
{ id: "ord-104", status: "open" },
{ id: "ord-105", status: "late" },
];
const SNAPSHOT = "orders-v1";
const MAX_PAGE_SIZE = 2;
function encodeCursor(cursor) {
return Buffer.from(JSON.stringify(cursor)).toString("base64url");
}
function decodeCursor(value) {
try {
const cursor = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
if (cursor.snapshot !== SNAPSHOT || typeof cursor.afterId !== "string") {
throw new Error("cursor does not belong to this result set");
}
return cursor;
} catch (error) {
throw new Error(`invalid cursor: ${error.message}`);
}
}
function listLateOrders({ cursor, limit = MAX_PAGE_SIZE } = {}) {
const pageSize = Math.min(Math.max(limit, 1), MAX_PAGE_SIZE);
const filtered = orders
.filter((order) => order.status === "late")
.sort((a, b) => a.id.localeCompare(b.id));
const start = cursor
? filtered.findIndex((order) => order.id === decodeCursor(cursor).afterId) + 1
: 0;
if (cursor && start === 0) throw new Error("cursor points outside the snapshot");
const items = filtered.slice(start, start + pageSize);
const last = items.at(-1);
const nextCursor = last && start + items.length < filtered.length
? encodeCursor({ snapshot: SNAPSHOT, afterId: last.id })
: undefined;
return {
items,
nextCursor,
complete: nextCursor === undefined,
snapshot: SNAPSHOT,
notice: nextCursor
? "More matching orders exist. Continue only if the task needs all of them."
: "This result is complete for the current snapshot.",
};
}
const first = listLateOrders();
assert.deepEqual(first.items.map((item) => item.id), ["ord-101", "ord-103"]);
assert.equal(first.complete, false);
assert.equal(typeof first.nextCursor, "string");
const second = listLateOrders({ cursor: first.nextCursor });
assert.deepEqual(second.items.map((item) => item.id), ["ord-105"]);
assert.equal(second.complete, true);
assert.equal(second.nextCursor, undefined);
assert.deepEqual(
[...first.items, ...second.items].map((item) => item.id),
["ord-101", "ord-103", "ord-105"],
);
assert.throws(() => listLateOrders({ cursor: "not-a-cursor" }), /invalid cursor/);
console.log("pagination fixture passed");
Salve como mcp-pagination-fixture.mjs e execute:
node mcp-pagination-fixture.mjs
O teste prova quatro propriedades locais: a ordem é estável, a primeira página declara que está incompleta, a segunda não repete registros e um cursor inválido não é aceito. Ele não prova que todos os clientes MCP seguirão a página seguinte, nem que o snapshot de um banco de produção ficará disponível pelo tempo necessário.
Como expor esse envelope pela tool?
O adaptador MCP deve devolver o envelope como dado estruturado e uma explicação curta para o modelo. O detalhe exato depende da geração do SDK, por isso o exemplo abaixo é intencionalmente ilustrativo:
const result = listLateOrders(args);
return {
content: [{
type: "text",
text: result.complete
? "The result is complete for this snapshot."
: "The result is partial. Use nextCursor only when more records are needed.",
}],
structuredContent: result,
};
O teste de contrato para servidores MCP em TypeScript é o lugar certo para acrescentar a verificação de descoberta, schema e chamada. Inclua pelo menos um caso que confira complete: false, um segundo caso que use o cursor recebido e um caso que confirme que uma resposta incompleta não é descrita pelo teste como lista final.
Se a tool declarar outputSchema, o schema deve representar também os estados de erro e de continuação que o cliente precisa tratar. Não use uma mensagem de texto escondida como única fonte de verdade. O texto ajuda o modelo; a estrutura permite que o host, o teste e o log tomem decisões sem fazer parsing de prosa.
Paginar é sempre a melhor escolha?
Não. A decisão depende do que o agente precisa fazer com os dados:
| Necessidade | Interface preferível | Motivo |
|---|---|---|
| Encontrar poucos candidatos | Busca filtrada com limite pequeno | O servidor reduz o conjunto antes de usar o contexto. |
| Comparar todos os registros | Agregação no servidor | O modelo recebe o resultado da operação, não milhares de linhas. |
| Exportar ou reconciliar tudo | Arquivo ou handle de exportação | O dado completo pode ser processado fora da conversa. |
| Explorar um conjunto moderado | Paginação com cursor | O agente pode continuar de forma explícita e limitada. |
| Esperar uma mudança externa | Polling com scheduler e deadline | O próximo horário não fica sob controle livre do modelo. |
Essa escolha aparece nas discussões de praticantes sobre tratar uma página como o conjunto completo e sobre paginar uma ferramenta que retorna muitos registros. Use esses relatos para reconhecer sintomas e vocabulário, não como prova de que uma estratégia sempre é superior.
O MCP de codebase RAG para agentes que não leem tudo parte de uma premissa parecida: recuperar somente o contexto relevante costuma ser melhor do que despejar o repositório inteiro. Para dados transacionais, a forma concreta pode ser filtro, ordenação, agregação ou exportação, mas o princípio é o mesmo: o agente não deve usar o contexto como banco de dados acidental.
O que observar no runtime?
Registre o suficiente para explicar uma resposta incompleta sem salvar dados desnecessários:
- identificador da execução e da consulta;
- nome da tool e versão do contrato;
- snapshot ou escopo lógico usado pela página;
- quantidade de itens devolvidos e limite aplicado;
- presença de
nextCursor, sem registrar o cursor em texto aberto quando ele carrega informação sensível; - motivo da parada:
complete,page_limit,cursor_expired,invalid_cursorouexport_required.
O guia de rastreamento de tool calls com OpenTelemetry cobre a correlação entre run, tool, tentativa e resultado. A telemetria ajuda a responder por que o agente parou, mas não substitui a guarda no dispatcher. O controle de página precisa impedir a próxima chamada antes que ela atinja o backend.
Método e limites
Consultei a documentação atual do cliente e do servidor do MCP TypeScript em 20/11/2026. Ela sustenta a separação entre a paginação de operações de lista do protocolo e os dados estruturados retornados por uma tool. Também examinei discussões públicas de praticantes para encontrar dúvidas sobre completude, filtragem e exportação. Essas discussões não foram usadas como prova técnica.
A fixture foi escrita para este artigo e executada localmente com Node.js. Ela usa uma lista fixa e um snapshot artificial, portanto não é um benchmark, não mede tokens e não demonstra comportamento de um modelo. A assistência de IA ajudou a organizar a pesquisa, revisar o texto e produzir as localizações; não executou um agente de produção nem forneceu uma medição de qualidade. Quando preciso prolongar uma sessão de depuração com menos contexto repetido, uso o RemoteCode, uma ferramenta minha.
Conclusão
Paginação de tool consiste em declarar a diferença entre "estes são os registros que encontrei nesta página" e "esta consulta terminou". Um cursor opaco, uma ordenação estável, um limite por execução e um campo de completude dão ao runtime uma decisão que não depende de adivinhar a intenção do modelo.
Quando o agente precisa de poucos candidatos, filtre no servidor. Quando precisa de todos, considere agregação ou exportação. Use páginas navegáveis para exploração controlada, e deixe o teste provar que uma resposta incompleta não passa por completa.