MCP Tool Limits in Cursor and Claude Code: Why Too Many Servers Break Your Agent

Every MCP server you connect adds tools, and every tool adds a definition the model has to read: a name, a description, and a schema. Connect enough servers and the agent starts to pick the wrong tool, runs out of context, or hits a cap with an error you have not seen before. The rules differ between Cursor and Claude Code, and in both cases they have changed during 2026, so this guide separates what is documented, what staff said on the forum, and what individual users reported.

Why too many tools breaks agents

• Context cost. The Claude Agent SDK documentation says tool definitions can consume large portions of the context window, and gives 50 tools using 10 to 20K tokens as an example. That is context you cannot spend on code and conversation.
• Selection accuracy. The same page says accuracy degrades with more than 30 to 50 tools loaded at once. Similar names and vague descriptions make it worse.
• Provider caps. A model provider may reject a request with too many tool definitions. A Cursor staff reply describes this as a per-model cap.
• More moving parts. Each server is another process or endpoint that can time out, need authentication, or return a giant result.

Cursor: what is known about the limit

The takeaway: if you see the cap error, you are probably on an older version or an older flow; update first. If you do not, do not assume you have unlimited tools, since selection accuracy and context cost still apply. Staff advice for the CLI was fewer active servers per project, checking counts with cursor-agent mcp list and list-tools. Related reading: Cursor Connection Failed and HTTP/2 errors.

Claude Code: tool search does the heavy lifting

Per the Agent SDK documentation, tool search is on by default. When it is active, tool definitions are withheld from the context window; the agent gets a summary of available tools and searches for relevant ones, loading up to five of the most relevant by default. The catalog limit is 10,000 tools. It adds one round trip each time Claude searches, and with fewer than about 10 small tools, loading everything upfront is typically faster. You control it with ENABLE_TOOL_SEARCH:

Some models and deployments fall back to loading definitions upfront, and ENABLE_TOOL_SEARCH cannot override that. Setting CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS also keeps tool search off. One caveat worth knowing: a GitHub issue (number 40314) reported on Claude Code v2.1.86 that an HTTP MCP gateway exposing about 250 tools loaded roughly 120K tokens upfront while stdio servers were deferred correctly. That is a single user report with no maintainer comment on the page we read, and it may be fixed in later versions. Check your own setup with /context rather than assuming.

Symptoms, causes, and fixes

How to prune safely

1. See what is connected. In Claude Code run /mcp for servers and tool counts, and /context for what fills the window. In the Cursor CLI use cursor-agent mcp list.
2. Scope servers to projects. Claude Code has local (default), project, and user scopes. Project scope stores the server in .mcp.json and shares it through version control; user scope loads in all your projects. Keep rarely used servers out of user scope.
3. Disable without removing. Toggle a server off in /mcp; Claude Code records this per project. Use claude mcp remove <name> to delete it.
4. Remove duplicates. Two servers exposing a tool called search force the model to guess.
5. Name tools for search. The SDK docs note that names such as search_slack_messages surface for a wider range of requests than query_slack, and descriptions with specific keywords match more queries than generic ones.
6. Keep results small. Paginate or filter in the server instead of returning thousands of tokens.

A script that audits your tool budget

This script takes the tool lists from your servers and reports the count, an estimated token cost per server (a rough characters-divided-by-four estimate, since real counts depend on the tokenizer), duplicate tool names, and advice. It also mirrors the documented auto and auto:N rule so you can see when tool search would activate. Its tests run without any MCP client installed.

import json
from dataclasses import dataclass


@dataclass
class ServerReport:
    name: str
    tools: int
    est_tokens: int
    share: float          # fraction of all tool tokens


def est_tokens(tool: dict) -> int:
    """Very rough estimate: about 4 characters per token. Real counts depend on the model's tokenizer."""
    return max(1, len(json.dumps(tool, separators=(",", ":"))) // 4)


def audit(servers: dict, context_window: int = 200_000, soft_limit: int = 50,
          tool_search_pct: float = 10.0) -> dict:
    """servers maps a server name to its list of tool dicts (name, description, inputSchema)."""
    reports, seen, dupes = [], {}, []
    total_tools = total_tokens = 0

    for name, tools in servers.items():
        t = sum(est_tokens(x) for x in tools)
        reports.append(ServerReport(name, len(tools), t, 0.0))
        total_tools += len(tools)
        total_tokens += t
        for x in tools:
            tn = x.get("name", "")
            if tn in seen and seen[tn] != name:
                dupes.append((tn, seen[tn], name))
            seen.setdefault(tn, name)

    for r in reports:
        r.share = r.est_tokens / total_tokens if total_tokens else 0.0
    reports.sort(key=lambda r: r.est_tokens, reverse=True)

    pct = 100.0 * total_tokens / context_window if context_window else 0.0
    advice = []
    if total_tools > soft_limit:
        advice.append(f"{total_tools} tools are connected; docs say selection accuracy degrades past 30-50 loaded at once.")
    if pct >= tool_search_pct:
        advice.append(f"Tool definitions are about {pct:.1f}% of the context window, above the {tool_search_pct:g}% auto threshold; "
                      "make sure tool search is active (ENABLE_TOOL_SEARCH).")
    if reports and reports[0].share > 0.5 and len(reports) > 1:
        advice.append(f"Server '{reports[0].name}' holds {reports[0].share:.0%} of tool tokens; disable or trim it first.")
    for tn, a, b in dupes:
        advice.append(f"Tool name '{tn}' exists in both '{a}' and '{b}'; duplicates confuse selection.")

    return {"total_tools": total_tools, "est_tokens": total_tokens, "pct_of_context": pct,
            "servers": reports, "duplicates": dupes, "advice": advice}


def tool_search_activates(deferrable_tokens: int, context_window: int, setting: str = "auto") -> bool:
    """Mirror of the documented ENABLE_TOOL_SEARCH rule for auto and auto:N."""
    if setting in ("", "true"):
        return True
    if setting == "false":
        return False
    pct = 10.0 if setting == "auto" else float(setting.split(":", 1)[1])
    return deferrable_tokens >= context_window * pct / 100.0

def tool(name, n=40):
    return {"name": name, "description": "x" * n, "inputSchema": {"type": "object"}}


def test_totals_and_sorting():
    r = audit({"a": [tool("a1", 400)], "b": [tool("b1", 40), tool("b2", 40)]})
    assert r["total_tools"] == 3
    assert [s.name for s in r["servers"]] == ["a", "b"]
    assert abs(sum(s.share for s in r["servers"]) - 1.0) < 1e-9


def test_heavy_server_is_called_out():
    r = audit({"big": [tool("t", 4000)], "small": [tool("u")]})
    assert any("'big'" in a and "disable or trim" in a for a in r["advice"])


def test_soft_limit_and_context_share_advice():
    many = {"s": [tool(f"t{i}", 200) for i in range(60)]}
    r = audit(many, context_window=20_000)
    assert any("60 tools" in a for a in r["advice"])
    assert any("auto threshold" in a for a in r["advice"])


def test_duplicate_names_across_servers():
    r = audit({"a": [tool("search")], "b": [tool("search")]})
    assert r["duplicates"] == [("search", "a", "b")]
    assert any("duplicates" in a for a in r["advice"])


def test_small_setup_has_no_advice():
    assert audit({"a": [tool("x")]})["advice"] == []


def test_tool_search_rule_matches_docs():
    cw = 200_000
    assert tool_search_activates(19_999, cw, "auto") is False
    assert tool_search_activates(20_000, cw, "auto") is True
    assert tool_search_activates(10_000, cw, "auto:5") is True
    assert tool_search_activates(9_999, cw, "auto:5") is False
    assert tool_search_activates(0, cw, "true") is True
    assert tool_search_activates(10**9, cw, "false") is False

Treat the numbers as a guide for where to prune first, not as exact measurements. Use /context for the real figure in Claude Code. For rate limits on the server side, see MCP server rate limits, and for protocol-level failures, MCP protocol errors.

Timeouts and output limits you may hit next

• MCP_TIMEOUT sets the server startup timeout in milliseconds, for example MCP_TIMEOUT=10000 claude for 10 seconds.
• MCP_TOOL_TIMEOUT sets the tool-call time limit across servers in milliseconds; a per-server timeout in .mcp.json overrides it for that server.
• MAX_MCP_OUTPUT_TOKENS raises the output cap (default 25,000 tokens); the warning at 10,000 tokens is fixed, and long text results over 50,000 characters are saved to a file unless the server raises the tool's own limit.

Sources

• Claude Code documentation: Scale to many tools with tool search
• Claude Code documentation: Connect Claude Code to tools via MCP
• Claude Code issue 40314: tool search and HTTP MCP servers (single user report)
• Cursor forum: Regarding the quantity limit of MCP tools (not official documentation)
• Cursor forum: CLI MCP tool limits (staff replies; not official documentation)
• Cursor forum: Frequent Connection Failed errors (not official documentation)

Frequently asked questions

Keep reading