Mcp Builder

MCP Builder

An MCP server is judged by one thing: how well it lets an agent actually get real tasks done. Design for the calling LLM, not for API completeness.

1. Research first

• Read the spec, don't guess. Start at https://modelcontextprotocol.io/sitemap.xml,

fetch pages with a .md suffix for markdown (e.g. .../specification/draft.md). Review architecture, transports, and tool/resource/prompt definitions — the protocol moves, so check current.

• Understand the target API you're wrapping: auth, endpoints, rate limits,

pagination, error formats.

2. Choose the stack

• TypeScript + @modelcontextprotocol/sdk — default. Strong SDK, good

compatibility, models write it well. pnpm add @modelcontextprotocol/sdk zod.

• Python + FastMCP — when the surrounding code is Python (research/ML).

pip install mcp (FastMCP is included).

• Transport: stdio for local servers (the common case — runs as a

subprocess of the client). Streamable HTTP for remote servers; prefer stateless JSON (simpler to scale than stateful sessions/streaming).

3. Design the tools (this is where quality lives)

• Coverage vs. workflow tools. Comprehensive endpoint coverage gives agents

flexibility to compose; workflow tools bundle a common multi-step task. When unsure, lean to coverage. Add a workflow tool when one task takes many calls.

• Names: action-oriented, consistently prefixed — github_create_issue,

github_list_repos. The agent finds the right tool by its name.

• Descriptions: concise, say what it does and when to use it. This is the

agent's only guide — invest here.

• Inputs: validate with a schema (zod in TS, type hints/Pydantic in

Python). Mark required vs optional; give defaults.

• Outputs: return focused, relevant data. Support pagination/filtering so a

call can't dump 10k rows into the context window.

• Errors are instructions. A failed call should tell the agent how to

recover: what was wrong, what to try next — not a raw stack trace.

4. Minimal shape

TypeScript (stdio):

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
import { z } from "zod"

const server = new McpServer({ name: "my-service", version: "0.1.0" })

server.tool(
  "myservice_search",
  "Search items by query. Returns up to `limit` matches with id + title.",
  { query: z.string(), limit: z.number().int().max(50).default(10) },
  async ({ query, limit }) => {
    try {
      const results = await api.search(query, limit)
      return { content: [{ type: "text", text: JSON.stringify(results) }] }
    } catch (e) {
      return { content: [{ type: "text", text: `Search failed: ${e.message}. Check the query is non-empty and the API token is set.` }], isError: true }
    }
  }
)
await server.connect(new StdioServerTransport())

Python (FastMCP):

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-service")

@mcp.tool()
def myservice_search(query: str, limit: int = 10) -> str:
    """Search items by query. Returns up to `limit` matches."""
    ...

if __name__ == "__main__":
    mcp.run()   # stdio by default

5. Test it like an agent would

• Run locally and inspect with the MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js.

• Write an evaluation: a handful of realistic tasks, then check whether an

agent can complete each using only the tools + descriptions. Fix the tools the agent misuses or can't find — that's the real bug, not the code.

• Add it to a client config (Claude Code / claude.ai / Cursor) and dry-run the

top tasks.

Review checklist (for an existing server)

• [ ] Tool names consistent, prefixed, action-oriented
• [ ] Every description says what + when, concisely
• [ ] Inputs schema-validated; outputs focused + paginated
• [ ] Errors guide recovery
• [ ] Right transport (stdio local / streamable HTTP remote, stateless)
• [ ] Secrets from env, never hardcoded
• [ ] An eval proves an agent can do the real tasks

Credit

Tool-design guidance adapted from the mcp-builder skill in anthropics/skills. Spec is authoritative: https://modelcontextprotocol.io.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hdprajwal
• Source: hdprajwal/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.