← Back to Build

Common Mistakes

The top issues we see across the scoreboard ecosystem — and how to avoid every one of them.

The State of MCP Server Quality

We score thousands of MCP servers. The same mistakes come up again and again. This guide covers the most impactful ones — ranked roughly by how often we see them and how much they hurt your score.

Good news: Every mistake on this page is fixable. Most take less than an hour. Fixing even half of these will move your server into the top tier.

1. Missing or Poor Descriptions

The single most common issue. A tool without a description is invisible to agents — they have to guess what it does from the name alone.

What We See

  • Tools with no description field at all
  • Descriptions that say what it does but not when to use it
  • Missing description on individual schema parameters
  • Using prose to state constraints ("must be between 1 and 100") instead of JSON Schema keywords like minimum/maximum

The Fix

  • Every tool gets a 1–2 sentence description: verb + resource + when to use it
  • Every parameter gets its own description
  • Read the Tool Naming & Descriptions guide for the full pattern

2. Too Many Tools

The "one tool per API endpoint" anti-pattern. Developers wrap their entire REST API as individual MCP tools, creating servers with 50, 100, or even 200+ tools.

Why It's a Problem

  • LLM accuracy drops significantly when tool counts exceed 20–40
  • Models are virtually guaranteed to fail at tool selection with 100+ tools
  • Each tool definition consumes context window tokens — 30+ tools can eat 20% of the window before any work begins
  • Some clients have hard limits (Cursor caps at 40 MCP tools; extras are silently ignored)

The Fix

  • Keep 5–15 tools per server
  • Design tools around outcomes, not API endpoints
  • Split large domains into multiple focused servers
  • Combine related operations (e.g., one manage_user with an action enum instead of separate create/update/delete/get tools)

3. Returning Too Much Data

Tools that dump entire API responses into the context window without filtering or pagination.

What We See

  • List endpoints returning 1,000+ items with no limit
  • Full JSON objects with every field when only 3 are relevant
  • No pagination — all results in one response
  • Verbose error messages with full stack traces

The Fix

  • Add limit (default 20–50) and cursor parameters to every list tool
  • Return only the fields the agent needs, not the full API response
  • Summarize large results: "Found 1,247 results. Showing first 20."
  • Read the Schema Design guide for pagination patterns

4. No Input Validation

Research across 2,600+ MCP implementations found alarming rates of vulnerability:

  • 82% use file system operations prone to path traversal
  • 67% use APIs susceptible to code injection
  • 34% use APIs vulnerable to command injection

Real-World CVEs

  • CVE-2025-68143 (CVSS 8.8): Path traversal in Anthropic's own MCP Git Server — accepted arbitrary file paths without validation
  • CVE-2025-6514 (CVSS 9.6): Remote code execution in mcp-remote npm package (437K downloads) via OS commands in OAuth fields

The Fix

  • Validate and sanitize every input parameter before use
  • Canonicalize file paths and check they're within allowed directories
  • Never build shell commands with string concatenation — use parameterized APIs
  • Use your schema's enum, pattern, minimum/maximum constraints as your first line of defense

5. No Authentication

Multiple independent security audits tell a consistent story:

  • 41% of servers in the official MCP registry have zero authentication (Feb 2026 audit)
  • 30% of 706 scanned servers had no auth at all (Aug 2025 scan)
  • 88% of servers that do require credentials use static long-lived secrets (API keys, PATs)
  • Only 8.5% of servers implement OAuth

The Fix

  • If your server accesses any protected resource, implement authentication
  • Prefer OAuth 2.1 over static API keys where possible
  • Never bind to 0.0.0.0 by default — use 127.0.0.1 for local servers
  • Implement proper auth discovery per the MCP auth spec

6. Logging to Stdout (stdio Transport)

The #1 cause of mysterious connection failures in stdio-based MCP servers. Any output to stdout — including from logging libraries, debug prints, or third-party dependencies — corrupts the JSON-RPC stream.

The Fix

  • Use console.error (stderr) for all logging
  • Configure logging libraries to write to stderr or to files
  • Audit third-party dependencies for stdout writes
  • Test your server with stdio transport before shipping

7. Silent Failures & Generic Errors

Tools that return {"error": "something went wrong"} or, worse, return success with empty results when something failed.

The Fix

  • Use isError: true for tool-level errors with specific messages
  • Use JSON-RPC 2.0 error codes for protocol errors
  • Include the failing input value and a recovery suggestion in every error
  • Read the Error Handling guide for the full pattern

8. Schemas That Lie

When your inputSchema doesn't match what the tool actually accepts. The agent generates arguments matching the schema, but the server rejects them or behaves unexpectedly.

What We See

  • Parameters marked as optional that are actually required
  • Enum values in the schema that the server doesn't handle
  • Schema says "type": "string" but the tool actually expects a specific format (UUID, date, email)
  • Schema includes parameters that the tool ignores entirely

The Fix

  • Auto-generate schemas from your code (Zod in TypeScript, Pydantic in Python)
  • Validate example payloads against your schema in CI
  • Use the MCP Inspector to verify tool definitions

9. Supply Chain Risks

MCP servers are a new attack surface. Real incidents have already occurred:

  • A malicious npm package postmark-mcp silently copied every email to the attacker's server (Sep 2025)
  • "Rug pull" attacks: a server starts legitimate, gets approved, then tool definitions are updated with malicious instructions
  • Tool poisoning: hidden instructions in tool descriptions/schemas that manipulate the AI agent

The Fix

  • Pin MCP server versions — don't auto-update without review
  • Audit tool definitions after every update
  • Use the mcpserver-audit tool to scan for known vulnerabilities
  • Publish your server on npm/PyPI/Docker Hub for package registry vetting

10. Stateful Scaling Without Sticky Sessions

MCP is a stateful protocol. Deploying multiple server instances behind a load balancer without sticky sessions causes requests to hit the wrong instance and fail silently.

The Fix

  • Use sticky sessions if running multiple instances behind a load balancer
  • Or use stateless HTTP mode (each request creates a fresh transport context)
  • Test with multiple instances before going to production

Quick Audit Checklist

  • Every tool has a meaningful description (not just a name)
  • Every parameter has a description
  • Server exposes 15 or fewer tools
  • All list tools support pagination (limit + cursor)
  • All inputs are validated and sanitized
  • No shell commands built with string concatenation
  • File paths are canonicalized and checked against allowed directories
  • Authentication is implemented for any non-public resource access
  • No logging to stdout on stdio transport
  • Errors return specific messages with recovery paths
  • Schemas match actual tool behavior (tested in CI)
  • Server version is pinned in client configurations
  • Server doesn't bind to 0.0.0.0 by default

Essential Resources

Security Audits & Research

Vulnerability Research

Supply Chain Security

Tool Overload & Design

Best Practices & Comprehensive Guides

OAuth & Auth Implementation