mcp-builder

Building Custom MCP Servers

MCP (Model Context Protocol) servers extend what I can do by exposing new tools. I can write, register, and use them across sessions.

File locations

• Server code: /workspace/group/mcp-servers/<server-name>/index.js
• Shared dependencies: /workspace/group/mcp-servers/package.json
• Registration: /workspace/group/.mcp.json

All paths under /workspace/group/ persist across container restarts.

---

Step-by-step: Create and register an MCP server

1. Set up shared dependencies (first time only)

All MCP servers share a single node_modules at the mcp-servers/ root. Only do this once:

mkdir -p /workspace/group/mcp-servers
cd /workspace/group/mcp-servers
if [ ! -f package.json ]; then
  npm init -y
  # Add "type": "module" for ES module support
  node -e "const p=require('./package.json'); p.type='module'; require('fs').writeFileSync('package.json', JSON.stringify(p, null, 2)+'\n')"
  npm install @modelcontextprotocol/sdk zod
fi

2. Write the server

Create /workspace/group/mcp-servers/<name>/index.js:

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

server.tool(
  "tool-name",
  "Description of what this tool does",
  { param: z.string().describe("A parameter") },
  async ({ param }) => ({
    content: [{ type: "text", text: `Result: ${param}` }],
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

Node resolves imports from the shared node_modules up the directory tree — no per-server install needed.

3. Test it

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test"},"protocolVersion":"2024-11-05"}}' | node /workspace/group/mcp-servers/<name>/index.js

Should return a JSON response without errors.