MCP servers often fail in predictable ways. Avoiding these mistakes saves debugging time and protects users.
Too Many Tools
Exposing every API endpoint as a tool bloats context and confuses models. Fix: offer fewer, task-oriented tools.
Vague Descriptions
"Gets data" tells the model nothing. Fix: describe purpose, usage, inputs and outputs precisely.
Logging to stdout
In stdio servers, stray output corrupts the protocol. Fix: log to stderr.
Huge Outputs
Returning thousands of records floods context. Fix: paginate, filter and summarise.
Unhelpful Errors
Stack traces don't help models recover. Fix: return clear error messages with suggestions.
Weak Authorisation
Skipping token validation or accepting tokens meant for other services. Fix: validate tokens and apply per-user permissions.
Unsafe Input Handling
Passing arguments into shell commands or SQL unsafely. Fix: validate inputs and use parameterised queries.
Ignoring Side Effects
Write tools without clear warnings or confirmation hints. Fix: mark destructive tools and keep them separate from read tools.
No Tests
Fix: test with an inspector, automated tests and real model interactions.