How Not to Write an MCP Server  🔗 **Source:** [How Not to Write an MCP Server](https://towardsdatascience.com/how-not-to-write-an-mcp-server/) > [!note]+ Document Notes > tags: > - #mcp > - #developer-diary > - #observability > - #ai-agents > - #lessons-learned > - #roni-dover > Author: Roni Dover > Source: Towards Data Science > Reference: https://towardsdatascience.com/how-not-to-write-an-mcp-server/ > date created: 2025-05-13 18:45 > > # Title: 🧠 How Not to Write an MCP Server: Lessons in Real-World Implementation > <!-- deep-read:sections start --> ## Table of Contents: - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#-notes) - [📖 References](#-references) - [🗣️ Paraphrase](#-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🔍 DARVO Analysis](#-darvo-analysis) - [🔍 SEO Evaluation](#-seo-evaluation) - [🎯 Conclusion](#-conclusion) --- ## 📝 Summary: Roni Dover reflects on the challenges of building an MCP (Model Context Protocol) server for a dynamic code analysis tool in an observability platform. The piece is structured around five major lessons learned—from overwhelming the agent with too much data, to time format issues, agent training strategies, clarity of API descriptions, and documenting JSON for AI understanding. Dover advocates for developer empathy with AI agent limitations, and iteratively tuning tooling for reliability, relevance, and clarity. --- ## 📖 Main Content: Dover’s retrospective on building an MCP server candidly outlines hard-won insights developers need when working at the edge of AI integrations. His five core lessons highlight both technical design principles and the nuance of human-AI collaboration. ### 🗒️ Notes #### 🔹 Stack Overview: - **Client Tools**: Cursor, VS Code - **Server Stack**: .NET with the official MCP SDK #### 🧱 Lesson 1: Don’t Dump All Data - Initial assumption: more data = more power for the agent. - Issue: verbose API response (360k+ characters) overwhelmed the model. - Result: model ignored data or failed to process key insights. - Fix: - Added a **nested hierarchy** to responses. - Created dimension-based **queryable APIs** to allow agents to navigate context in chunks. - Switched to a higher context window model (Gemini 2.5 Pro) to confirm limits. #### 🕰 Lesson 2: Time Isn’t Obvious - Agents may not know current datetime. - They default to ISO 8601 durations (e.g., P7D). - Solution: document and handle duration formats. #### 💡 Lesson 3: Correct and Teach - Agents misuse environment identifiers from prompts. - Old system failed silently → no feedback loop. - New system returns valid suggestions and errors. - Agents learn from responses and adapt behavior. #### 📣 Lesson 4: Lead with Intent - Original tool descriptions were too functional. - Agent ignored tools unless prompted specifically. - Rewrite emphasized **use cases**, improving tool activation in relevant prompts. #### 🧾 Lesson 5: Document JSON - JSON lacks native comments. - Added `_comment` field with rich metadata on score calculations and context. - Improved agent reasoning and explanation capabilities. #### 🛠 Architecture: SSE vs STDIO - STDIO-based MCP = local CLI, harder to update. - SSE = hosted microservice endpoint, easier versioning, better alignment with app lifecycle. - Supergateway proxy used to bridge client support gaps. --- ## 📖 References: - Dover, Roni. [How Not to Write an MCP Server](https://towardsdatascience.com/how-not-to-write-an-mcp-server/) --- ## 🗣️ Paraphrase: 1. *Original*: “The basic premise was therefore to allow the agent to work its ‘magic’, with more data potentially meaning more hooks for the agent to latch on.” *Paraphrased*: I believed giving the AI more data would increase its ability to find useful patterns—but too much actually overwhelmed it. 2. *Original*: “While it is tempting to simply describe what the API is doing, sometimes the generic terms don’t quite allow the agent to realize the type of requirements for which this functionality might apply best.” *Paraphrased*: Just describing API functionality isn’t enough—clarity around its *intended use cases* makes it much more effective for AI to apply. --- ## 📰 Newsletter: **🧪 Developer Lessons from Building an MCP Server** When AI meets observability, it’s not always magic—sometimes it's 360,000 characters of JSON that leave your agent totally clueless. Roni Dover’s latest dev diary offers a goldmine of practical takeaways from building an MCP server to power dynamic code analysis. From smart data structuring to agent education and JSON annotation hacks, this is a must-read for anyone integrating AI into developer tools. Bonus: lessons on whether to go SSE or STDIO for serving your MCP. 👉 [Read the article](https://towardsdatascience.com/how-not-to-write-an-mcp-server/) --- ## ✅ Action Items: - **Contributor Docs**: Write community-facing tutorials on best practices for MCP server JSON structure and API responses. - **Tooling**: Improve WordPress and open-source observability tools with SSE compatibility and agent-friendly APIs. - **Education**: Build course modules around real-world AI tooling pain points, including agent query behavior and error feedback loops. - **OSPO Alignment**: Highlight MCP design tradeoffs in open-source code intelligence tools, advocating for transparency in AI system integration. --- ## 🧪 Hypotheses: - Smaller, context-aware data responses yield better AI behavior than full data dumps. - Explicit error messaging improves agent learning over time. - SSE architecture reduces versioning friction compared to STDIO in MCP scenarios. ### 📊 Methodology: - Compare agent success rates pre/post refactor using test suites with structured prompts. - Run user research on latency and success rates between SSE and STDIO deployments. - Analyze frequency of tool invocation pre/post doc rewriting. ### ❓ Questions: - Can AI agents reliably learn from structured tool error responses? - Should MCP specs evolve to support native metadata alongside JSON? - How do different LLMs respond to identical data structures in high-volume scenarios? ### 🔮 Future Research: - Effects of JSON `_comment` fields on multi-agent collaboration. - Longitudinal studies on prompt adaptation post-agent error correction. - Standardizing time formats and temporal logic in agent APIs. ### 💡 Implications: - Raises UX stakes for AI toolchains—developers must design for agents, not just humans. - Supports argument for hybrid server-client architectures in modern AI infrastructure. - Could inform future open protocols for AI observability integrations. --- ## 🧠 Learning Styles Assessment: **Readability Score**: ~Grade 12; suitable for technical readers. - **Visual Learners**: ✅ Illustrative images from Midjourney *Improve*: Use flowcharts for data handling architecture. - **Aural Learners**: ❌ No auditory supplement *Improve*: Embed a narrated walkthrough or podcast. - **Verbal Learners**: ✅ Story-based explanations *Improve*: Glossary of MCP terms for newer devs. - **Physical Learners**: ❌ *Improve*: Add “try this” coding scenarios with GitHub. - **Logical Learners**: ✅ Step-by-step diagnostics and structure *Improve*: Charts comparing SSE vs STDIO. - **Social Learners**: ❌ *Improve*: Invite dev feedback via forums or Twitter. - **Solitary Learners**: ✅ Introspective, diary-style voice. - **Naturalistic Learners**: ❌ *Improve*: Use natural metaphors for data flow patterns. --- ## 📊 Accessibility Assessment: - **Screen Reader Compatibility**: Not confirmed *Improve*: Ensure semantic HTML and alt text. - **Keyboard Navigation**: Likely okay in Medium *Improve*: Audit for tab indexing and control access. - **Contrast and Readability**: ✅ Clear text, no visual noise. - **Text Resizing**: ✅ Responsive Medium layout *Improve*: Test with custom zoom levels and dark mode. --- ## 🌍 DEIB Assessment: - **Cultural Relevance**: 🌐 Globally neutral, tech-focused - **Inclusive Language**: ✅ Informal and inviting - **Neurodiversity Support**: ✅ Clear structure, lesson-based - **Representation**: ❌ No mention of users or teams - **Psychological Safety**: ✅ Encouraging tone, candid mistakes shared *Recommendations*: - Add a sentence about team collaboration or diverse test users. - Introduce personas (e.g., “junior dev vs. senior ops”) for broader relatability. --- ## ✅ Logical Validity: **Strengths**: - *Causal Reasoning*: Errors → empty results → traced to model limits. - *Inductive Insight*: From agent behavior patterns, improved tool design. - *Analogies*: Implicit learning cycle likened to human debugging. - *Balanced View*: Doesn’t overly blame the model or user. **No fallacies detected**. No strawmen, hasty generalizations, or appeals to authority. --- ## 🔍 DARVO Analysis: - **Deny**: ❌ Not present. Author owns mistakes transparently. - **Attack**: ❌ No negative framing toward models, tools, or platforms. - **Reverse Victim/Offender**: ❌ Clear personal accountability and debugging process. **Tone**: Thoughtful, honest, and encouraging. Promotes learning and iteration. --- ## 🔍 SEO Evaluation: - **Keywords**: ✅ MCP, AI, observability, dynamic code analysis - **Meta Description**: ✅ Engaging first paragraph - **Title Tag**: ✅ Clear, curiosity-driven - **Header Usage**: ✅ Strong “Lesson” formatting - **Content Length**: ✅ 2,000+ words - **Internal Links**: ❌ *Improve*: Link to other Dover posts or MCP GitHub. - **External Links**: ✅ GitHub MCP repo included. - **Image Optimization**: ✅ Author-generated graphics - **Mobile Optimization**: ✅ Medium’s default responsive layout - **Engagement**: ✅ Promotes social sharing - **Schema Markup**: ❌ *Improve*: Add article schema for better indexing. --- ## 🎯 Conclusion: This post is a real-world masterclass in AI integration for developers. Through humor, humility, and hard-won fixes, Roni Dover shows us what it takes to turn an MCP server from functional to powerful. His five lessons serve as a blueprint not just for technical success, but for a deeper partnership between developers and AI agents—one based on clarity, structure, and mutual learning. --- <!-- deep-read:sections end --> 📄 **Full text:** ![[Full Document Contents/Articles/How Not to Write an MCP Server|How Not to Write an MCP Server, Roni Dover]] ## Highlights - a big gap between implementing a workable MCP to one that can actually integrate with user needs and usage scenarios, even beyond those you have anticipated. ([View Highlight](https://read.readwise.io/read/01jv5v09jp424ywg4j7nshzbgn))