5 min read

AI & Agents

MCP Has Millions of Downloads. Most Teams Still Use It Wrong.

I wired MCP into my local setup and got three things wrong: a one-line tool description, too many tools, and a context window I forgot was shared. Here is what fixing each one changed.

MCP mistakesModel Context ProtocolMCP server tool descriptions

MCP Has Millions of Downloads. Most Teams Still Use It Wrong. · Products Decoded
By Debashis Nayak · Products Decoded12 Apr 2026

My first MCP tool was called search_files, and its entire description was “Search for files.” Claude called it constantly. I asked about code and it searched for files. I asked for a summary of a document and it searched for files. I asked what time it was, and I swear it nearly searched for files.

That was one of three mistakes I made wiring MCP into my local setup. I am writing them down because the protocol is no longer a niche experiment. As of 12 April 2026, MCP had crossed 97 million SDK downloads, and I still see the same three problems in most setups I look at.

What did my AI setup look like before MCP?

Embarrassing. Claude reached my file system through one custom script. My database had its own wrapper, and so did Jira. Each new tool I wanted the model to touch meant another weekend of integration code, auth debugging and connections that snapped whenever an API changed.

Then MCP clicked for me. The specification itself did little for me, and seeing how it changed the way I build did the rest. The old setup was spaghetti. The new one looked like a circuit board.

Before MCP, giving a model access to a calendar, a database and a file system meant three custom integrations, each tied to one model. Switch models and you rewrite them. With MCP I write one server per tool, and any compatible model can use it. Claude, GPT-4o, Gemini or a local Llama all work. The protocol handles the handshake. I think portability matters more here than convenience.

The “USB-C for AI” line is popular, but I find it a bit off. A cable is passive. In MCP the model decides which tool to call, when, in what order, and what to do with the result. That is closer to an agent holding permissions.

Mistake 1: Why do vague MCP tool descriptions cause chaos?

I built my server the way I would build a REST API: define the endpoints, document them, deploy, move on. But the consumer of an MCP tool is a model that decides from natural language alone whether to use it. Nobody is reading your docs page.

My search_files description gave Claude nothing to go on, so it guessed, and it guessed often. I rewrote it:

Search for files matching a specific pattern in the project directory. Use only when the user explicitly asks to find or locate a file by name or extension. Do not use for reading file contents or general browsing.

Unnecessary calls dropped by roughly 80%. That is my estimate from watching the behavior, since I did not build a benchmark for it.

Treat every tool description as a small system prompt. Say when to use the tool, when to leave it alone and what input it expects. The wording of the description mattered more to behavior than the code behind it.

Mistake 2: How many MCP tools is too many?

The setup I see most on GitHub connects 10 to 15 servers and exposes 60-plus tools. File system, database, shell commands and API credentials all sit there at once with no filtering. It resembles handing a new hire root access on day one and hoping it goes well.

My local setup runs the opposite way. A context.md file defines what the model knows. My MCP servers define what it can do. I keep those two separate on purpose. The model can read my project structure and run a few pre-approved commands. It cannot push to production, delete data or reach credentials outside its sandbox.

My rule is to start with the smallest tool set that works and add a tool only after I hit a specific limitation. Every exposed tool is more surface area for behavior I did not intend. An agent that can execute shell commands plus one loosely worded tool plus one ambiguous request equals a command I never meant to run. For me, sandboxing is the whole security model.

Mistake 3: Does MCP eat your context window?

It does, and I only noticed because the output got worse.

Tool definitions sit in the context window for the whole session. The cost shows up every time the model reasons about its next action, not only when a tool gets called. When I first connected 8 servers with roughly 50 tools, Claude’s reasoning on complex tasks seemed to degrade. My read is that the model had not gotten worse. Fifty tool definitions were taking room it needed for thinking. I did not run a controlled test, so treat that as my diagnosis rather than a measurement.

Some teams in the ecosystem are moving toward meta-tools. You expose 3 or 4 of them and let the model compose actions or write code on the fly. I have seen reports of 40 to 60% token savings from that pattern, though I have not tried it myself.

My own answer was simpler: run fewer servers. I now operate 4 or 5 servers with about 12 to 15 tools in total, which covers roughly 90% of what I do day to day. Each tool is a line item in a budget, and I try to spend that budget on purpose.

What changed after fixing all three?

BeforeAfter
”Search for files.”A description that says when to call it and when not to
8 servers, about 50 tools4 to 5 servers, about 12 to 15 tools
Everything exposed by defaultMinimum tool set, sandboxed, grown on demand
Reasoning that felt worse on hard tasksContext left for the actual work

Why should a product manager care about MCP?

You do not need to write servers to need to understand them. Any AI product that has to do things, and not just chat, needs an execution layer, and MCP is turning into that layer for a lot of teams. Which tools to expose, which guardrails to build and how to scope agent permissions are product decisions as much as engineering ones. I make the same argument about production AI in general in AI in production is a product job.

A PM who tells the team to “just connect the AI to our APIs” will probably get a fragile demo. A PM who has thought about tool surface area, descriptions and sandbox boundaries before anyone writes code is much more likely to get something that survives contact with users.

A checklist if you are starting out

  1. Install Claude CLI and connect the filesystem MCP server first. The before and after difference is easiest to see there.
  2. Read each tool description as if you were the model. If you cannot tell from the text when to call it, rewrite it.
  3. Write your context.md before your MCP servers. What the model knows and what it can do deserve separate designs.
  4. Sandbox from day one and add permissions deliberately.
  5. Run npm run inspector against your server and watch what the model does with your tools. The behavior is often surprising.

I am still unsure where the right ceiling is. Fifteen tools works for me, but I would not be shocked if someone with a tighter task runs happily on five.