sc:mcp-builder

MCP Builder — ship a production Model Context Protocol server

Build an MCP server that an agent can safely call. Optimize for small, well-typed tools and a tight security surface — an MCP tool is remote code execution by another name.

Step 0 — scope it

• What does it expose? Tools (actions), resources (readable data), prompts (templates) — pick only what's needed. Fewer, sharper tools beat many fuzzy ones.
• Transport: stdio for a local process the client spawns (most common, simplest); streamable HTTP for a hosted/shared server. Don't expose stdio servers on a network.
• Secrets: which env vars/keys does it need? They stay in the client config / env, never hard-coded.

Step 1 — scaffold (reuse the official SDK, don't hand-roll the protocol)

TypeScript/Node (@modelcontextprotocol/sdk):

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-mcp", version: "1.0.0" })

server.tool(
  "get_thing",
  "Fetch a thing by id. Read-only.",
  { id: z.string().describe("the thing id") },
  async ({ id }) => ({ content: [{ type: "text", text: await fetchThing(id) }] }),
)

await server.connect(new StdioServerTransport())

Python (mcp package) mirrors this with FastMCP + @mcp.tool().

Step 2 — design each tool well

• Name = a verb_noun the model will guess (search_issues, not do).
• Description = one line: what it does + side effects + "read-only" if it is.
• Input schema = strict (zod/pydantic). Validate everything; reject unknown fields. Describe each param.
• Output = structured content (text/json/image). Return useful errors as content, not silent failures.
• Idempotency & side effects — mark mutating tools clearly; never auto-delete without confirmation.

Step 3 — security (do this, not later)

• Validate and sanitize all inputs; path-escape checks for any filesystem tool (refuse paths that escape the project root). Parameterize any DB/query tool — never string-concat user input.
• Secrets only from env; never log them; never echo them in tool output.
• Least privilege: a read tool must not be able to write. Time out and bound expensive calls.
• For HTTP transport: require auth, bind to 127.0.0.1 unless intentionally public, rate-limit.