{
  "id": 18823303,
  "title": "Writing an MCP Server: The Tool Description Is the Whole API",
  "url": "https://urgent.news/2026/11/08/writing-an-mcp-server-the-tool-description-is-the-whole-api",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-11-08T00:24:34.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/grimicorn/writing-an-mcp-server-the-tool-description-is-the-whole-api-8cm"
  },
  "original_language": "en",
  "account": "Creating an MCP server boils down to one essential truth: the tool description is the entire API. Many first MCP servers replicate existing REST APIs, exposing one tool per endpoint, but the Model Context Protocol focuses on the design, not the implementation. The SDK takes care of transport, discovery, and validation, leaving you to define the tools and their descriptions.\n\nYour audience is an LLM reading JSON Schema at runtime, not a developer reading documentation. The minimum viable server is now the stable release targeting the 2026-07-28 spec revision. It's split into two packages: @modelcontextprotocol/server and @modelcontextprotocol/client, with tool schemas written in Standard Schema, compatible with Zod v4, Valibot, or ArkType.\n\nHere's a minimal server for a deploy pipeline with a single read-only tool:\n\n1. Import required modules: @modelcontextprotocol/server, @modelcontextprotocol/server/stdio, Zod v4, and your custom function listDeploys.\n2. Create a new McpServer instance with a name and version.\n3. Register the tool \"list-recent-deploys\" with an inputSchema, title, description, annotations, and an async handler.\n4. In the handler, fetch the list of deploys using your custom function, check if any deploys exist, and return the formatted result. If no deploys are found, return a failed result with a helpful error message.\n5. Start the server using serveStdio and log a message indicating the server is running on stdio.\n\nKey points to remember:\n\n- The inputSchema defines the only schema you write; the SDK handles the rest.\n- Every .describe() in the schema becomes part of the JSON Schema the model sees, providing essential documentation for the arguments.\n- Use console.error when running on stdio to avoid corrupting the JSON-RPC stream.\n- When a model sends invalid arguments, return a failed result with a helpful error message, guiding the model on the next steps.\n- For results that another program will consume, add an outputSchema and return structuredContent alongside the human-readable content. The SDK will validate this value against the schema before returning it.",
  "summary": "Most first MCP servers look the same: someone wraps their existing REST API, exposes one tool per endpoint, ships it, and then watches the model call the wrong tool with the wrong arguments. The protocol worked fine. The design didn't. That's the part the tutorials skip. The Model Context Protocol handles transport, discovery, and validation for you, and the official SDK hides almost all of it.…",
  "key_points": [
    "The tool description defines the entire API in MCP protocol.",
    "SDK handles transport, discovery, and validation of tools.",
    "Minimal server includes @modelcontextprotocol/server and @modelcontextprotocol/client packages."
  ],
  "editors_take": "Shifting focus from traditional endpoint implementation to descriptive schema design forces developers to treat LLMs as the primary users of their APIs rather than human programmers.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}