You’ve probably noticed a pattern when you try new LLM-backed or adjacent tools, especially in the developer space. Once you get oriented, the first few interactions are delightful. You start to gain an instinct for what the tool can do. Then you begin to explore the boundaries, either out of curiosity or necessity, and you find them faster than you’d like. Suddenly, the delight wears off, and the boundaries feel a bit constraining. especially I felt this way writing v0 of our Tessl MCP server. Having used a few and gone through Anthropic’s quickstart tutorial, I still wasn’t 100% sure what to expect. I found the process equal parts magical and frustrating. I want to share a few things I learned along the way that might help anyone approaching MCPs for the first time. Setup Actually writing the MCP server was straightforward. In our case, the server wraps a few tools that were already exposed elsewhere for easy invocation. All I had to do was enumerate those tools with simple names and descriptions, then wire them up to the right functions. I’ve seen more complex examples, but I imagine for most products, this part will be reasonably quick. most What surprised me wasn’t the code, it was watching how LLM-backed tools interacted with the MCP server I had built. Or rather, how often they didn’t. Tool discovery Anthropic’s quickstart uses a weather API, where the tool is called get_weather. This is a good example, because LLMs already know what weather is, and if a user asks about it, a tool named get_weather makes sense to use. There’s no need for explanation or discovery. It just works. get_weather But my MCP wasn’t exposing a public API. It was describing a new product with a novel process and new vocabulary. There were no existing priors for the LLM, Claude Code in my case, to draw from. The tools were defined, but they weren’t recognised. Unlike traditional chat setups, MCP servers don’t include a system prompt, so there was no way to globally explain what the product was or how the tools were meant to be used. Even with good descriptions, Claude Code often tried anything other than calling the tools I had exposed: guessing what I meant, attempting operations itself, or researching more information online (good effort, to be fair, but not so amusing after  tokens). This led to a frustrating loop. recognised What kind of user is this for? This led to a broader realisation (did everyone but me already know this?): MCP servers work best when the human user already knows what they’re doing. Most existing examples assume that the user is proficient in the tools provided, and just wants a new interaction pattern. In that case, the user can use precise vocabulary, steer the conversation, and help the LLM pick the right tools. MCP servers work best when the human user already knows what they’re doing. But I was designing for the opposite: users who were new to the product and needed the LLM to help them learn what was possible, or suggest next steps. That turned out to be a tricky fit. With no context and no training on the toolset, the LLM often flailed, or ignored the tools completely. Remedies Here are a few ideas for how to remedy this issue, many of which we’ve applied ourselves: Adding an “intro” tool: A “fake” tool that just returns a blob of context: what the product is, what the tools do, and some ideas for how to use them. Here, you can give LLM-specific instructions about what to do next.Named tools more descriptively: Give the LLM the best chance of correctly choosing a tool by naming it very obviously. A pattern like : might be a mouthful, but it leaves very little to guess, for example: tessl:create_spec_for_new_tile as opposed to a first pass create_spec. You could also consider mapping many tools to the same functions if there’s a chance of users struggling to articulate their intentions clearly — in this example, I might consider adding make_spec or new_spec, which have the same behaviour.Used IDE-level priming: Adding .cursor.rules.json, claude.md, and other environment-specific files to preload guidance wherever possible was helpful. Of course, you need to decide how and when to init this guidance, and how to make it clear to users that they’ll get the most out of your MCP server if they complete this step. Adding an “intro” tool: A “fake” tool that just returns a blob of context: what the product is, what the tools do, and some ideas for how to use them. Here, you can give LLM-specific instructions about what to do next. Adding an “intro” tool: Named tools more descriptively: Give the LLM the best chance of correctly choosing a tool by naming it very obviously. A pattern like : might be a mouthful, but it leaves very little to guess, for example: tessl:create_spec_for_new_tile as opposed to a first pass create_spec. You could also consider mapping many tools to the same functions if there’s a chance of users struggling to articulate their intentions clearly — in this example, I might consider adding make_spec or new_spec, which have the same behaviour. Named tools more descriptively: very tessl:create_spec_for_new_tile create_spec make_spec new_spec Used IDE-level priming: Adding .cursor.rules.json, claude.md, and other environment-specific files to preload guidance wherever possible was helpful. Of course, you need to decide how and when to init this guidance, and how to make it clear to users that they’ll get the most out of your MCP server if they complete this step. Used IDE-level priming: Still Early Days My colleague Rob pointed out to me that most MCP developers will probably try to troubleshoot using LLMs, reaching less and less for StackOverflow. I wonder how much of these speedbumps we’ll have to encounter only by doing — or if it’ll be primarily LLMs that teach us how to use connector technologies like this. using Overall, this technology is still in its early days. Since I built this first version, the ecosystem has already evolved — new interfaces, better patterns, more robust examples. I expect that a lot of the pain points I hit will smooth out quickly. this technology is still in its early days

Building My First MCP Server: Equal Parts Wonder and Frustration

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

8 AI Tools That You Should Be Excited About (And Adopt!)

The Noonification: How Often Do NFTs Pass The Howey Test? (1/13/2023)

Darwin's Hybrid Intelligence to Align AI & Human Goals for Startups & VCs

The Noonification: White Man (11/26/2022)

The Noonification: The Metaverse is a Sh*tshow (11/2/2022)

8 AI Tools That You Should Be Excited About (And Adopt!)

The Noonification: How Often Do NFTs Pass The Howey Test? (1/13/2023)

Darwin's Hybrid Intelligence to Align AI & Human Goals for Startups & VCs

The Noonification: White Man (11/26/2022)

The Noonification: The Metaverse is a Sh*tshow (11/2/2022)

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps