MCP Server Builder Skill

Description

This skill guides you through building production-quality MCP servers that integrate external APIs and services with Claude. It covers the full lifecycle: project setup, tool definitions, input validation, error handling, testing, and distribution.

Instructions

When the user wants to build an MCP server, follow this workflow:

Step 1: Project Scaffolding

Copy
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

Copy
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}

Step 2: Server Structure

Copy
// src/index.ts
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-server',
  version: '1.0.0',
});

// Define a tool
server.tool(
  'search-docs',
  'Search documentation by keyword',
  {
    query: z.string().describe('Search query'),
    limit: z.number().optional().default(10).describe('Max results'),
  },
  async ({ query, limit }) => {
    try {
      const results = await searchDocs(query, limit);
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(results, null, 2),
        }],
      };
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `Error searching docs: ${error.message}`,
        }],
        isError: true,
      };
    }
  }
);

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

Step 3: Tool Design Best Practices

Copy
// GOOD: Clear name, description, typed parameters
server.tool(
  'create-ticket',
  'Create a support ticket in the ticketing system',
  {
    title: z.string().min(1).max(200).describe('Ticket title'),
    priority: z.enum(['low', 'medium', 'high', 'critical']).describe('Ticket priority'),
    description: z.string().describe('Detailed description of the issue'),
    assignee: z.string().email().optional().describe('Email of assignee'),
  },
  async (params) => {
    // Implementation
  }
);

// BAD: Vague name, no validation, generic params
server.tool('do-thing', 'Does a thing', { data: z.any() }, async (p) => { ... });

Step 4: Configuration

Add to Claude Code settings:

Copy
// .claude/settings.json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Step 5: Distribution

For npm distribution:

Copy
// package.json
{
  "name": "@myorg/mcp-server-docs",
  "bin": { "mcp-server-docs": "dist/index.js" },
  "files": ["dist/"]
}

Users install with:

Copy
{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@myorg/mcp-server-docs"]
    }
  }
}

Rules

• Always use Zod for input validation — never trust raw input
• Every tool must have a clear, descriptive name and description
• Return isError: true for error responses so Claude handles them correctly
• Use environment variables for API keys and secrets — never hardcode
• Add #!/usr/bin/env node shebang for CLI distribution
• Test each tool independently before publishing
• Handle rate limits and timeouts gracefully
• Log errors to stderr (not stdout — stdout is the MCP transport)
• Keep tool count reasonable (<20) — split into multiple servers if needed
• Document required environment variables in the README

Examples

User: Build an MCP server for our internal API Action: Scaffold project, define tools matching API endpoints, add auth, test, and configure

User: Add a new tool to my existing MCP server Action: Add tool definition with proper schema, validation, and error handling

User: My MCP server isn't connecting Action: Check: stdio transport, no stdout logging, correct settings.json path, build compiled