MCP server connects but its tools never appear (tool-count ceiling)

Any AI coding tool Last checked 2026-10-23

What you saw

The server is green. The server shows as connected, running, no errors in the logs. The tools panel lists them. Then you ask the agent to do something on that service and it apologises: it cannot access GitHub, it cannot reach Figma, it has no way to check the ticket.

You name the tool explicitly and the agent still says it does not have it. The tools are visible to you in the MCP panel but the model was never sent them.

The symptom appears right after you add or enable one more server. The previously working server stops working, even though nothing about it changed.

In Cursor specifically, a warning appears at the limit: you have more tools than the limit and some tools may not be available to the agent. In older builds the extras were ignored with no diagnostic at all.

In VS Code Copilot Chat the request is rejected outright with an error: more tools than are allowed per request.

The server's own logs show it received tools/list and replied with the full list, but the client never surfaces them to the model.

What it actually means

Every MCP tool is a name, a description and a JSON schema that the client ships to the model on every single turn, before your prompt and before any file content. Tool count is therefore a context cost, not a free menu.

Clients set ceilings to protect the context budget and keep tool selection accurate. The cap is normally total across every enabled server, not per server, so three small servers can put you over the line while no single server looks large.

Reported limits as of October 2026: Cursor around 40 tools across all enabled MCP servers, VS Code Copilot Chat 128 per chat request (the only figure in official docs), Windsurf Cascade 100 across all servers. Claude Code has no fixed count and defers definitions through tool search by default. Claude Desktop publishes no hard cap but loads every enabled definition into the conversation context.

Cursor's own MCP documentation does not publish a number. A March 2025 forum thread measured an effective cap where the agent received only the first 40 tools and later ones vanished; a March 2026 thread reports more than 80 tools with no warning. Treat 40 as the safe planning number and confirm against your installed version, because these limits move between releases.

The cap is only the first problem. Before you ever hit a hard limit, models pick worse: with dozens of overlapping names like search_issues, search_repos and search_code the wrong tool gets chosen more often. OpenAI's function-calling guidance suggests fewer than 20 functions available at the start of a turn. GitHub trimmed Copilot's built-in tool set from 40 to 13 and expanded the rest on demand, which improved success rates by 2 to 5 points and cut average latency by about 400 ms.

This is not a connection failure. The transport is healthy and the handshake completed. The client is filtering the tool list before it reaches the model, and the MCP protocol has no signal that says "tools rejected".

The fix

1. Count the tools before you change anything. Export the tool list from each server and count the total, not the per-server totals. The cap applies to the sum.

2. Turn off the servers you are not using for this task. Each enabled server burns tool slots whether or not you call its tools. In Cursor, toggle servers from the MCP settings in the sidebar rather than removing them.

   # Before: 5 servers, 78 tools, 38 of them never reach the model
   # After: 2 servers, 24 tools, all 24 reach the model

3. If you own the server, shrink its tool surface. Combine related operations behind one tool with an action parameter, or split rarely-used capabilities into a separate server you enable only when needed.

   // Before: 12 fine-grained tools
   // After: 3 composite tools
   {
     "name": "database",
     "inputSchema": {
       "type": "object",
       "properties": {"action": {"enum": ["query", "mutate", "schema"]}}
     }
   }

4. Split one big server into per-workflow servers and enable only the one you need for the task at hand.

   # mcp.json
   {
     "mcpServers": {
       "db-read":  {"command": "...", "args": ["--mode", "read"]},
       "db-write": {"command": "...", "args": ["--mode", "write"]},
       "db-admin": {"command": "...", "args": ["--mode", "admin"]}
     }
   }

5. In Cursor, check the real count for yourself and keep it under 40 as a working budget.

   cursor-agent mcp list
   cursor-agent mcp list-tools <server>
   # count across every enabled server, then disable the ones you do not need

6. Start a new chat after toggling servers. Old conversations keep the tool list they were started with, so toggling mid-session does not change what the model already has.

   # toggle servers on/off, then open a fresh chat

7. In VS Code Copilot Chat, the request fails outright rather than silently. If you hit the 128-tool error, the only fix is fewer enabled tools in that request.

How to stop it happening again

Treat tool count as a budget with a number attached: about 40 for Cursor, under 128 for VS Code, under 100 for Windsurf. Check the count before you add a server, not after something breaks.

One vendor server is a surface area, not one tool. GitHub alone exposes issues, pull requests, search and checks. Count tools, not servers.

Keep a small always-on set and toggle the rest per task. A default of two or three servers you always need beats ten you always enable.

Prefer sharply distinct tool names. Overlapping names like search_issues and search_code hurt accuracy even when you are well under the cap.

Split your config by scope. Project-specific servers belong in a project-level mcp.json, not the global one, so they do not follow you into unrelated sessions.

If you are building an MCP server, expose a --minimal or --mode flag that reduces the advertised tool count for everyday use, and document the tool count in your README so your users can budget for it.

Related questions

Why does the server show as connected if the tools are dropped?

The MCP protocol separates connection lifecycle from tool discovery. The client considers the connection successful once initialize and the capabilities handshake complete. Tool registration happens after that, and the cap check happens there. Because the protocol has no tools-rejected signal, nothing surfaces as an error.

Is the limit per server or across all servers?

Across all enabled servers. That is the part that catches people out: three servers with 15 tools each is 45, over Cursor's 40, even though no single server looks oversized. Count the sum.

What is the actual tool limit for Cursor, VS Code and Claude Code?

As of October 2026, reported figures are around 40 tools for Cursor, 128 per chat request for VS Code Copilot Chat (the only one published in official docs), and 100 across all servers for Windsurf Cascade. Claude Code has no fixed count and defers definitions through tool search by default, so its practical limit is the context window. Claude Desktop publishes no hard cap. Limits move between releases, so confirm against your installed version.

Can I raise the ceiling?

Not from the user's side. These are limits inside the client, not a setting exposed to you. The workable answer is a smaller board: fewer servers enabled, fewer tools per server, or a proxy that fronts several servers behind two or three tools.

Is this the same as the -32000 connection closed error?

No. A -32000 error means the transport broke, so nothing works from that server. Here the transport is fine and the handshake completed; the client simply refuses to register some tools. See the -32000 page for transport failures.

How do I confirm the tools reached the client at all?

Call tools/list against your server directly with a JSON-RPC request and count what comes back. If that returns the full list and the agent still cannot use them, the drop is on the client side and you are almost certainly at the ceiling.

Do I need to reduce tools even if I am under the cap?

Probably yes. The hard cap is blunt, and the practical ceiling sits below it. With dozens of overlapping tool names the model picks the wrong one more often, which shows up as the agent saying it cannot do something it half knows how to do. GitHub got 2 to 5 points better success and roughly 400 ms lower latency by trimming 40 built-in tools to 13 and loading the rest on demand.