5 MCP Server Mistakes That Make Your AI Agent Worse

The MCP ecosystem is growing fast, but most servers make the same avoidable mistakes — from naive API wrapping to stale documentation. Here's what to fix.

5 MCP Server Mistakes That Make Your AI Agent Worse

The MCP ecosystem has thousands of servers in the official registry. Every major AI coding assistant speaks the protocol natively — Claude Code, Cursor, Codex CLI, ChatGPT desktop. Building an MCP server has never been easier.

Building a good one is a different story. Thoughtworks put “naive API-to-MCP conversion” on Hold in its Technology Radar. OWASP published a dedicated MCP Top 10 — a protocol earns its own Top 10 list only after enough implementations get it wrong.

Most of these problems trace back to a handful of mistakes that developers keep making. They don’t just add technical debt — they actively make the AI agents using your server produce worse results.

Mistake #1: Wrapping an API 1:1 as MCP tools

This is the most common anti-pattern. You have a REST API with 30 endpoints, so you create 30 MCP tools — one per endpoint.

Why it seems right: It’s the fastest path from “I have an API” to “I have an MCP server.” Every endpoint gets its own tool, clean mapping, done.

Why it breaks your agent: LLMs have finite context and limited tool-selection ability. Give an agent 30 tools and it has to figure out which ones to chain together, in what order, with what parameters — for every single request. That’s asking the model to reverse-engineer your API’s workflow logic from tool names and descriptions alone.

The real problems:

  • Tool overload degrades selection accuracy. The more tools you expose, the harder the model has to work to pick the right one. Thoughtworks’ Hold entry makes the same point: APIs are “granular, atomic actions” designed for human developers, and chaining them with an AI “can lead to excessive token usage, context pollution, and poor agent performance.”
  • Multi-step workflows become the agent’s problem. If “create a deployment” requires calling three endpoints in sequence, the agent has to discover that workflow itself. It will get it wrong. Often.
  • Error handling is inconsistent. Each thin wrapper surfaces a different error format from the underlying API. The agent sees HTTP 422 from one tool and a JSON error object from another, with no way to reason about what went wrong.

The fix: Design tools around user intents, not API surface area. Instead of list_repos, get_repo, list_branches, get_branch_protection — build check_repo_status that internally orchestrates the calls and returns a structured summary. Fewer, smarter tools that do the heavy lifting so the agent doesn’t have to.

Mistake #2: Skipping input validation

MCP tools accept input from LLMs. LLMs hallucinate. This is not a theoretical concern.

An agent can send parameter values that don’t exist in your system, malformed dates, IDs it invented, or strings that happen to contain SQL fragments. If your MCP server passes these straight to a backend without validation, you’re running LLM-generated input against production systems with zero guardrails.

The OWASP MCP Top 10 devotes an entry to it — MCP05, “Command Injection & Execution,” covers untrusted input reaching an executor without proper validation or sanitization. Actively maintained servers have shipped exactly that bug, as the advisory below shows. Your weekend MCP server almost certainly has gaps too.

What good validation looks like:

  • Strict input schemas on every tool. Zod, JSON Schema, whatever your stack uses — define the exact shape, types, and constraints. Don’t accept string when you mean email. Don’t accept number when you mean integer between 1 and 100.
  • Validate before acting. Check that referenced IDs actually exist before making mutations. Verify permissions before executing. Return clear error messages that help the agent self-correct.
  • Sanitize for injection. LLM-generated strings should never be interpolated into SQL queries, shell commands, or template engines without sanitization. This sounds obvious, but a tool that fetches a URL the model supplied will happily fetch your metadata endpoint. GHSA-45gf-fjxp-cjpq (CVE-2026-54549, CVSS 8.3) is exactly that: meta-ads-mcp before 1.0.115 passed an image_url argument straight to an HTTP fetch with no scheme, host, or IP validation, so callers could reach loopback, private-network, and 169.254.169.254 cloud metadata addresses.

Mistake #3: Returning raw data instead of context

Your MCP tool queries a database and returns 200 rows of JSON. Or hits a docs API and returns the entire page. Or fetches a log file and dumps all 10,000 lines into the response.

The agent now has to find the three relevant lines buried in kilobytes of noise. Best case, it wastes context window and processing time. Worst case, the relevant information gets pushed out of the model’s attention window entirely and the agent misses it.

The problem isn’t the data — it’s the shape. MCP tools aren’t API endpoints serving a frontend that can render and filter. They’re serving an LLM that reads everything sequentially and has a fixed context budget.

What helps:

  • Return the relevant section, not the whole document. If the agent asks about React’s useEffect cleanup, return the cleanup section — not the entire Hooks reference page. @neuledge/context does this with section-aware full-text search: queries return the specific documentation section that matches, ranked by relevance, not the whole page.
  • Pre-process results. Filter, sort, and summarize before returning. If a database query returns 200 rows, return the top 10 most relevant with a count of total matches — not all 200.
  • Structure the response for LLM consumption. Instead of raw JSON arrays, return data with headers, labels, and context that help the model reason about the results.

Mistake #4: No rate limiting or resource bounds

An agentic coding session can call your MCP tools hundreds of times. A multi-agent workflow might have five agents running in parallel, each making dozens of tool calls. If your MCP server has no limits on concurrent requests, response sizes, or resource consumption, one runaway session can take down the server for everyone.

This isn’t hypothetical. Agentic loops retry on failure, and an agent that gets a timeout will often retry immediately — turning a momentary overload into a sustained one. Without bounds:

  • API quotas get exhausted. If your MCP server proxies a paid API, a single agentic session can burn through your monthly quota in minutes. There’s no human in the loop to notice costs climbing.
  • Response sizes blow up. A tool that returns “all matching results” without a cap can return megabytes of data, overwhelming the agent’s context and slowing every subsequent interaction.
  • Concurrent access overwhelms backends. Five agents hitting the same MCP server simultaneously can easily exceed what the underlying database or API can handle.

The fix: Treat your MCP server like a production service because it is one.

  • Per-session rate limits. Cap the number of requests any single session can make per minute. Return a clear error message so the agent knows to back off.
  • Response size caps. Paginate large results. Return a maximum number of items with a signal that more exist.
  • Graceful degradation. When overloaded, return a “server busy, try again in N seconds” response instead of timing out. Timeouts trigger retries; explicit backoff signals don’t.

Mistake #5: Serving stale documentation

Your MCP server serves library documentation indexed from a snapshot six months ago. The library has shipped two major versions since then. Functions have been deprecated, parameter names have changed, new patterns have replaced old ones.

The agent doesn’t know any of this. It queries your server, gets confident-looking docs for deprecated APIs, and generates code that looks right but uses a class that was renamed three versions ago. The developer spends an hour debugging their agent’s logic when the bug is actually a renamed function.

Why this happens more than you’d think:

  • Most documentation MCP servers index once and never update. The initial setup works, the docs are there, nobody sets up a refresh pipeline.
  • “Latest” isn’t always right either. If a team is pinned to v5 of a library but the MCP server indexed v6, every answer references the wrong API. The version mismatch cuts both ways.
  • Stale docs compound. One deprecated function call leads the agent down a path where it uses three more deprecated patterns to make the first one work. By the time the developer notices, the entire file needs rewriting.

Solutions:

  • Version-pinned documentation. Index docs for the exact version the team is using. @neuledge/context does this by indexing from specific Git tags — context add https://github.com/vercel/ai --tag v6.0.86 — so the agent always reads docs matching the installed version.
  • Automated refresh pipelines. If you’re serving “latest,” automate the re-indexing. A daily cron that re-pulls and re-indexes keeps drift under a day.
  • Use a maintained registry. Pre-built documentation packages from a community registry get updated regularly without manual intervention. It’s the difference between maintaining your own Linux kernel patches and using a package manager.

The checklist

Before you ship an MCP server — or install one from the registry — run through these five:

  1. Tools map to user intents, not API endpoints. If you’re exposing dozens, reconsider.
  2. Every tool has strict input validation. Schemas, type checks, sanitization. No raw LLM input hits your backend.
  3. Responses are shaped for LLMs. Relevant sections, not raw dumps. Summaries, not full datasets.
  4. Rate limits and resource bounds exist. Per-session caps, response size limits, graceful degradation under load.
  5. Documentation is current and version-aware. Indexed from a known version, refreshed automatically, not a stale snapshot.

The MCP ecosystem is maturing fast — the 2026-07-28 specification brought stateless sessions, improved authorization, and better extension points. But protocol improvements only help when the servers using them are well-built. These five mistakes are the difference between an MCP server that makes your AI agent better and one that silently makes it worse.

For the broader quality picture, see The MCP Server Explosion: Why More Servers Isn’t Better. For understanding when MCP is the right choice at all, see MCP vs Function Calling.

Get started

Building an MCP server for documentation? Start with a well-architected example:

npm install -g @neuledge/context
context add https://github.com/your-org/your-lib --tag v2.0.0
context serve