Hmbown/CodeWhale · error · anyhow::Error

{} exceeded the {}-item catalogue limit

Error message

{} exceeded the {}-item catalogue limit

What it means

Second leg of McpCatalogBudget: the running item count across pages of one catalogue method must stay within MAX_MCP_CATALOG_ITEMS = 4096 (crates/tui/src/mcp.rs:1281, 1318-1324). Exceeding it aborts that method's discovery and thus the connection - a guard against unbounded tool/resource/prompt catalogues.

Source

Thrown at crates/tui/src/mcp.rs:1319

    }

    fn observe_page(
        &mut self,
        result: &serde_json::Value,
        item_count: usize,
    ) -> Result<Option<String>> {
        self.pages = self.pages.saturating_add(1);
        self.items = self.items.saturating_add(item_count);
        self.bytes = self.bytes.saturating_add(serde_json::to_vec(result)?.len());
        if self.pages > MAX_MCP_CATALOG_PAGES {
            anyhow::bail!(
                "{} exceeded the {}-page catalogue limit",
                self.method,
                MAX_MCP_CATALOG_PAGES
            );
        }
        if self.items > MAX_MCP_CATALOG_ITEMS {
            anyhow::bail!(
                "{} exceeded the {}-item catalogue limit",
                self.method,
                MAX_MCP_CATALOG_ITEMS
            );
        }
        if self.bytes > MAX_MCP_CATALOG_BYTES {
            anyhow::bail!(
                "{} exceeded the {}-byte aggregate catalogue limit",
                self.method,
                MAX_MCP_CATALOG_BYTES
            );
        }
        let cursor = result
            .get("nextCursor")
            .and_then(|value| value.as_str())
            .map(str::to_owned);
        if let Some(cursor) = cursor.as_ref()
            && !self.seen_cursors.insert(cursor.clone())

View on GitHub (pinned to 8880682c63)

Solutions

1. Trim the catalogue server-side: expose fewer tools/resources/prompts.
2. Split the server into multiple focused MCP servers, each under 4096 items.
3. If you control the server, consider filtering by scope/profile so each consumer sees a bounded catalogue.

Example fix

# before: one gateway server exposing 6000 tools
# after: three MCP servers (git-tools, ci-tools, docs-tools), each < 4096 items

#!/usr/bin/env bash
# Probe total items across pages; must stay <= 4096 per method.
url="https://mcp.example.com/mcp"; cursor=""; items=0
while :; do
  body=$(curl -s "$url" -H 'content-type: application/json' \
    -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"${cursor:+,\"params\":{\"cursor\":\"$cursor\"}}}")
  items=$((items + $(printf '%s' "$body" | jq '.result.tools | length')))
  [ "$items" -gt 4096 ] && { echo "would exceed 4096 items"; exit 1; }
  cursor=$(printf '%s' "$body" | jq -r '.result.nextCursor // empty');
  [ -z "$cursor" ] && break
done; echo "items=$items ok"

When it happens

Trigger: A server whose tools/list (or resources/prompts list) exposes more than 4096 items in total across its pages.

Common situations: Large API gateways, monorepo tool aggregators, or meta-servers that federate many upstreams into one catalogue.

Related errors

• {} exceeded the {}-page catalogue limit
• {} exceeded the {}-byte aggregate catalogue limit
• {} repeated pagination cursor; aborting
• Invalid MCP tool name: {prefixed_name}
• Ambiguous MCP tool name '{prefixed_name}' matches more than

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/82d02624b62e6266. Report an issue: GitHub.