MCP Best Practices: 7 Hard Lessons I Learned Building 5 MCP Servers (Full Checklists Included)

A developer who built five MCP servers shares seven hard-learned lessons for production deployments. Key mistakes include returning empty arrays that cause clients to hang, manually constructing JSON strings leading to parse errors, and implementing authentication incorrectly. The developer provides specific code examples and checklists to help others avoid these pitfalls.

Let me be honest with you — I've built five different MCP Model Context Protocol servers in the past three months, and I got almost everything wrong the first time. Like, really wrong. If you've been living under a rock like I was three months ago , MCP is the new standard that lets AI clients like Claude Desktop connect to your tools and data through a standardized protocol. The idea is beautiful: build once, works everywhere MCP is supported. No more custom integrations for every AI client. But here's the thing — the official docs are still catching up. Tutorials only show you the happy path. Production? That's where all the fun happens. After getting paged at 2 AM three times last month because my MCP server was hanging, I've collected some hard-earned lessons that I wish someone had told me before I started. Today I'm sharing them with you. Let's dive in. So here's the thing — I built my first MCP server for my personal knowledge base. Everything worked great in testing. I connected it to Claude Desktop, asked it to search for "MCP authentication", got results back, felt like a genius. Then I asked it to search for "xyzabc123" — something that definitely had no results. Claude just... hung. Spun forever. No timeout, no error, nothing. I restarted everything, checked logs, it looked like my server returned 200 OK with empty content. Turns out Claude didn't handle empty responses well at all. I learned the hard way: never return an empty array or empty content when there are no results . Return a human-readable message explaining that nothing was found. Here's what I do now Java example, but the principle applies everywhere : public class SearchKnowledgeHandler implements ToolCallHandler { @Override public Object handle ToolCallRequest request { List<KnowledgeResult results = searchService.search request.getQuery ; if results.isEmpty { // ❌ BAD: This will hang some clients // return Collections.emptyList ; // ✅ GOOD: Return a human-readable explanation return Collections.singletonList Map.of "result", "No results found for your query: '" + request.getQuery + "'. " + "Try different keywords or check your spelling." ; } return results; } } This one change fixed 80% of my "random hanging" issues. Different clients handle empty responses differently — some handle it fine, some don't. Why take the risk? A friendly message costs you nothing and saves everyone debugging time. I know what you're thinking — "JSON is simple, I can just concatenate strings." Stop. Don't do it. I did it. It cost me four hours of debugging why every other request failed. Here's what happened. I was in a hurry, wanted to get something working quickly. Instead of letting Spring Boot serialize my response objects, I manually built the JSON: // ❌ NEVER DO THIS. I BEG YOU. String badJson = "{\"result\": \"" + userInput + "\"}"; Everything worked fine until someone searched for My project is called "Papers" . The double quote inside the content broke the entire JSON. The client got a parse error, disconnected, and I spent hours wondering why my server was "randomly crashing". Lesson: Always, always, always let your framework serialize JSON for you. Never manually build JSON strings. Never. // ✅ Do this instead record SearchResponse List<Result results, String query {} return new SearchResponse foundResults, query ; // Framework handles serialization If you're using Go, use encoding/json . If you're using Python, use json.dumps . If you're using Node.js, use JSON.stringify . Doesn't matter what stack you're on — let the framework handle it . One unescaped character and your entire response is garbage. Save yourself the pain. Okay, this one surprised me. I read the spec, implemented API key authentication in the Authorization: Bearer {key} header — that's the standard way, right? Then I tried connecting with four different MCP clients. Guess what? Authorization: Bearer {key} ✅ X-API-Key: {key} ❌ didn't work api key={key} ❌ didn't work apiKey={key} different name ❌ also didn't workI spent three days going back and forth, debugging why my server wouldn't connect. The problem wasn't any of the clients — they all do it differently. MCP is still young, and there isn't consistent practice yet. The fix: Support all common locations. It's like 20 extra lines of code, and suddenly everyone can connect. Here's what I do in Java with a Spring OncePerRequestFilter : @Component public class McpAuthenticationFilter extends OncePerRequestFilter { @Override protected void doFilterInternal HttpServletRequest request, FilterChain filterChain throws ServletException, IOException { // Try all common locations String apiKey = getApiKeyFromAuthorizationHeader request ; if apiKey == null { apiKey = request.getHeader "X-API-Key" ; } if apiKey == null { apiKey = request.getParameter "api key" ; } if apiKey == null { apiKey = request.getParameter "apiKey" ; } if validateApiKey apiKey { request.getServletResponse .sendError HttpStatus.UNAUTHORIZED.value ; return; } filterChain.doFilter request, filterChain ; } private String getApiKeyFromAuthorizationHeader HttpServletRequest request { String header = request.getHeader "Authorization" ; if header = null && header.startsWith "Bearer " { return header.substring 7 ; } return null; } } Yes, putting the API key in the query string isn't "perfectly secure" because it might get logged in server logs. But guess what — users just want it to work . If some clients only support query params, you either support it or they can't use your server. Compatibility wins over purity here. If you're running a public service with sensitive data, you can always document the risks. For most personal MCP servers, it's totally fine. If you're running an MCP server that web-based AI clients will connect to and you probably are — lots of new MCP clients are web apps , you need CORS. And CORS means OPTIONS preflight requests. Here's the gotcha: OPTIONS requests don't send your authentication headers . That's just how browsers work. So if you have authentication enabled on all endpoints, your preflight request will get a 401 Unauthorized, the browser will block the request, and nothing works. I spent two hours on this. It's so frustrating because everything works fine with desktop clients they don't do CORS , but web clients just fail silently. Fix: Configure your CORS to allow the necessary headers, and make sure OPTIONS requests don't require authentication. Here's how I do it in Spring Boot: @Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings CorsRegistry registry { registry.addMapping "/ " .allowedOrigins " " // Restrict this to your actual clients in production .allowedMethods "GET", "POST", "OPTIONS" .allowedHeaders " " .exposedHeaders " " ; } } And make sure your authentication filter skips OPTIONS requests: @Component public class McpAuthenticationFilter extends OncePerRequestFilter { @Override protected boolean shouldNotFilter HttpServletRequest request { // Preflight OPTIONS requests don't have auth headers return request.getMethod .equals "OPTIONS" ; } // ... rest of the filter } That's it. This one change will save you from the weirdest "it works on desktop but not on web" debugging session. Cold starts are real. If you're running on Fly.io Heroku, or any free tier, your server might need 5-10 seconds to spin up and handle the first request. Some MCP clients have pretty strict timeouts — like 5 seconds. If you don't respond in time, they disconnect. I learned this one when my knowledge base MCP server kept timing out on the first request after cold start. The search was actually working, it just took 7 seconds, and the client gave up at 5. The trick: If you're on Spring Boot or any framework that supports it , enable flushing and send the headers early. This keeps the connection alive while your server is still processing. Here's a concrete example in Spring Boot where you can write the HTTP status and headers immediately: @PostMapping "/mcp/call" public void handleToolCall @RequestBody McpRequest request, HttpServletResponse response throws IOException { // Start writing early to keep the connection alive response.setContentType "application/json" ; response.setStatus HttpStatus.OK.value ; PrintWriter writer = response.getWriter ; // Do your slow processing here... ToolCallResult result = slowToolService.execute request ; // Write the actual result when you're done writer.write objectMapper.writeValueAsString result ; writer.flush ; } This works because the client opens the connection, gets the headers immediately, and keeps the connection open waiting for the body. No timeout. It's not pretty, but it solves the problem. For slow operations, this is a lifesaver. This is a super subtle one. Some MCP clients have issues with chunked encoding. If you don't explicitly set the Content-Length header, they might truncate your response — cut off the end, leaving invalid JSON. You get a parse error, and you can't figure out why because when you check your logs, the JSON looks complete. I only found this after comparing what my server sent vs what the client received byte-for-byte. Yep, the last few characters were missing. Why does this happen? Some clients don't handle chunked encoding correctly. If you generate the entire response before sending it which you usually do for MCP tool calls , you know the exact length. Just set it. Here's how to do it in Node.js/Express: js app.post '/mcp/call', req, res = { const result = handleRequest req.body ; const json = JSON.stringify result ; // ✅ Set Content-Length explicitly res.setHeader 'Content-Length', Buffer.byteLength json ; res.setHeader 'Content-Type', 'application/json' ; res.send json ; } ; In Java Spring Boot, if you're writing directly to the response: String json = objectMapper.writeValueAsString result ; response.setContentLength json.getBytes StandardCharsets.UTF 8 .length ; response.getWriter .write json ; It's one extra line, and it eliminates an entire category of weird "response truncated" errors. Why not? If you're running your MCP server 24/7 in production or even just want to know when it's down , add a simple health check endpoint. It doesn't need to do much — just return 200 OK. Fly.io, Kubernetes, most cloud providers can ping this endpoint and restart your container if it's unhealthy. I added this after my server went unresponsive for 12 hours because of a memory leak, and I had no idea. The simplest possible health check: @RestController public class HealthCheckController { @GetMapping "/health" public Map<String, Object health { return Map.of "status", "ok", "timestamp", System.currentTimeMillis , "service", "mcp-server" ; } } That's it. Five lines of code. Now your platform can automatically restart unhealthy instances. The peace of mind is worth it. I also add it to all my side projects now — even if I don't need it today, I'll thank myself later. Here's everything I go through before I ship any MCP server to production now. Print this out or save it somewhere — you'll need it: Authorization: Bearer , X-API-Key , api key query, apiKey query OPTIONS preflight requests skip authentication, allow necessary headers /health endpoint returns 200 OK for monitoringLet's be real — MCP is still young. It's exciting, but it's not all perfect. Here's my honest take after building five servers: tools/list and tools/call . That's it. You don't need a complex frontend or anything. Keep it simple.Building MCP servers has been a really fun learning experience for me. Three months ago, I'd never even heard of MCP. Today, I've got five different servers running for different projects, and I use them every day. The biggest realization I had? MCP flips the architecture on its head. Before MCP, we tried to put all the smarts inside our services. Now the AI client already has all the smarts — your service just needs to expose data and tools. That's it. Simple is better. Complexity is your enemy. All the lessons I shared in this article came from real production pain. I stepped in every pothole so you don't have to. Follow the checklist, test with multiple clients, keep things simple, and you'll be fine. Have you built an MCP server yet? What weird edge cases did you run into that I didn't cover here? I'd love to hear about your experiences in the comments — every bit of shared knowledge helps everyone in this new ecosystem. If you want to see how I implemented all this in a real Java MCP server, check out my open-source knowledge base project on GitHub: https://github.com/kevinten10/Papers https://github.com/kevinten10/Papers Go build something cool 🚀