A 360-line MCP server with no SDK: five decisions that stopped the agent from breaking links
After a "tool failed" reply, an agent guesses: it retries the call, changes the arguments, or apologizes. The author of a short-link service wrote a 360-line Node.js MCP server with no SDK that simply proxies the service's REST API. Errors come back as ordinary tool results, and batch operations report partial success. The takeaway: design API responses for the model as well.
AI-processed from Habr AI; edited by Hamidun News
Connecting an agent to your own service through the Model Context Protocol (MCP) is not hard. Making sure it doesn't get confused, fire off unnecessary requests, or corrupt data is. The developer of a short-link service shared his experience: his MCP server runs about 360 lines of plain Node.js, with no SDK and no dependencies, and nearly every line was added after Claude Code or Cursor behaved unexpectedly. The scenario is simple: the agent writes a newsletter or release notes, creates a link with UTM tags on its own, and then checks the clicks.
A thin wrapper instead of a second copy of the logic
The server contains no business logic of its own. It receives a tool call, makes a request to the existing REST API with a key, and returns the response. Validation, limits, and security checks stay on the API side.
This gives three advantages. The rules live in one place: if you change a limit or a URL check, every MCP client gets the change without a package update. The server runs locally via npx and needs only a key and the API address. And it is easy to test: it is a mapping of "tool → HTTP request."
The transport is simple too. The local server talks to the client over stdin and stdout using JSON-RPC 2.0 messages, one JSON string per line. Just in case, the parser also understands the Content-Length header format used in LSP. There are two details where it's easy to trip up: stdin arrives in chunks of arbitrary size, so you need a buffer that holds the unprocessed remainder, and nothing except protocol messages may be written to stdout. One forgotten console.log, and the client silently disconnects the server. Debug output must go to stderr.
Five decisions that turned out to matter most
Errors as data. If an API failure is returned as a JSON-RPC error, the client often shows the model nothing but "tool failed." The model then guesses: it retries the call, changes the arguments, or apologizes to the user. The author returns the error as a normal result with the flag isError: true, and the text goes into the context. Protocol errors are reserved for genuine breakdowns: an unknown method, an unknown tool, invalid JSON. The error text is written for the model: instead of a bare "401," the message reads "API_KEY is invalid. Create a key at…" Given that, the agent usually does not hammer the API again and instead tells the user where to get a key.
Annotations for dangerous tools. Tools can carry the hints readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, and clients use them to decide when to ask for confirmation. Deleting and disabling a link are marked as destructive, while listing links and reading statistics are marked as read-only. The description also includes the phrase "This cannot be undone," so the model asks the user again on its own. But these are only hints, not protection. The real constraints are the key's permissions and the checks on the server.
Predictable URL handling. Models like to "fix" links. If the user asks to add utm_source=newsletter, but the URL already has utm_source=partner, which one wins? The author decided: existing parameters are not overwritten, and the #fragment anchor is preserved, because someone set those tags on purpose in a live campaign. The rule is locked in by a test against the API and spelled out in the tool description. The general lesson: if a model can pass extra or contradictory input, the server's behavior must be deterministic and documented.
Partial success in batches. The shorten_urls tool creates several links at once. If one of ten fails validation, a thrown exception would make the model conclude that nothing succeeded, and it would rerun everything even though nine links already exist. So the API replies with an object containing the arrays created and errors, and the server returns it as a normal result, even on an HTTP error. The model retries only the failed items.
Images as images. A QR code in base64 text is several kilobytes of meaningless characters in the context, which means extra tokens and extra cost. MCP has an image content type: the client displays the picture, and a short text block accompanies it with the type and size. That is enough for the model to say "QR is ready, PNG, 4 KB."
What the author would do differently
Setup takes one command: claude mcp add with the key and the address, run through npx. For Cursor and Claude Desktop, the same setup is described in mcp.json. After that, you can give the agent instructions in plain text.
The author is candid about the approach's limits. API responses should have been designed for the model from the start: short error reasons and explicit partial success are useful for ordinary integrations too. Writing the protocol by hand makes sense for understanding it, but for resources, prompts, and the HTTP transport, the official SDK will save time. And you need to test on several clients at once: Claude Code, Cursor, and MCP Inspector display errors differently and decide differently when to ask for confirmation.
The practical takeaway for anyone building MCP on top of their own API: keep the logic on the server, write errors as instructions for the model, flag dangerous operations, and don't put into the context anything the model can't read.
- Nov 21, 2026Eight Open-Source Tools for AI Agents: Browser Use Leads with 121,000 Stars
- Nov 21, 2026Parallel Search Tops 26-API AI Agent Search Ranking With 83 Points
- Nov 21, 2026Text-to-cad: AI Agent Draws Robot Parts From a Description, Project Passes 26,000 Stars
- Nov 21, 2026A viral GTA 6 Claude clip looks fake: half an hour of control burned through the 5-hour Pro limit
Key Questions Answered
What are the key details on A thin wrapper instead of a second copy of the logic?
The server contains no business logic of its own. It receives a tool call, makes a request to the existing REST API with a key, and returns the response. Validation, limits, and security checks stay on the API side. This gives three advantages. The rules live in one place: if you change a limit or a URL check, every MCP client gets the change without a package update. The server runs locally via npx and needs only a key and the API address.
What are the key details on Five decisions that turned out to matter most?
Errors as data. If an API failure is returned as a JSON-RPC error, the client often shows the model nothing but "tool failed." The model then guesses: it retries the call, changes the arguments, or apologizes to the user. The author returns the error as a normal result with the flag isError: true, and the text goes into the context. Protocol errors are reserved for genuine breakdowns: an unknown method, an unknown tool, invalid JSON.
What the author would do differently?
Setup takes one command: claude mcp add with the key and the address, run through npx. For Cursor and Claude Desktop, the same setup is described in mcp.json. After that, you can give the agent instructions in plain text. The author is candid about the approach's limits. API responses should have been designed for the model from the start: short error reasons and explicit partial success are useful for ordinary integrations too.
Build & Ship Production AI Agents Without Boilerplate Code
Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.
The AI world, distilled — once a week
Seven stories that actually mattered, hand-picked. No noise, no reposts, no press releases.
Done! Check your inbox for a confirmation.