claudecodeui/claude-skills/mcp-builder.md

name	description
mcp-builder	Build MCP (Model Context Protocol) servers — stdio, HTTP/SSE, or remote. Covers tool design, auth, deployment, and testing.

MCP Builder Skill

Use when building a new MCP server or adding tools to an existing one.

MCP Server Types

• stdio — subprocess, local only, simplest
• HTTP/SSE — network accessible, supports auth, deployable
• Remote (Cloudflare Workers, etc.) — edge-deployed, global

Tool Design Principles

1. One tool = one atomic action. Don't bundle list+get into one tool.
2. Names are verbs: get_user, list_orders, create_invoice.
3. Required params only — use optional sparingly with sensible defaults.
4. Return structured JSON — always. Never plain strings.
5. Descriptive tool descriptions — the model reads these to decide which tool to call.
6. Error objects not exceptions — return {error: "message"} in the result, don't throw.

Minimal stdio Server (Node.js)

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "my-server", version: "1.0.0" }, {
  capabilities: { tools: {} }
});

server.setRequestHandler("tools/list", async () => ({
  tools: [{ name: "say_hello", description: "Say hello", inputSchema: {
    type: "object", properties: { name: { type: "string" } }, required: ["name"]
  }}]
}));

server.setRequestHandler("tools/call", async (req) => {
  if (req.params.name === "say_hello") {
    return { content: [{ type: "text", text: `Hello, ${req.params.arguments.name}!` }] };
  }
  throw new Error(`Unknown tool: ${req.params.name}`);
});

await server.connect(new StdioServerTransport());

Auth (HTTP servers)

• Static API key: Authorization: Bearer <key> header check
• OAuth 2.1 with PKCE for user-facing servers
• Never put secrets in tool responses

Testing

# Test with MCP inspector
npx @modelcontextprotocol/inspector node ./server.js

# Test tool call directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"say_hello","arguments":{"name":"world"}}}' | node server.js

.mcp.json Registration

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"]
    }
  }
}