Claude Official Skill: mcp-builder

What it is

The mcp-builder is an official Claude Code skill that guides the agent through creating high-quality MCP (Model Context Protocol) servers. MCP servers enable LLMs to interact with external services, databases, APIs, and tools through a standardized protocol. This skill encapsulates best practices for server architecture, tool definitions, resource handling, error management, and testing.

Developers building MCP integrations for Claude Code, Claude Desktop, or other MCP-compatible clients benefit most. The skill eliminates guesswork about MCP server structure and ensures the output follows the protocol specification.

How it saves time or tokens

Building an MCP server from scratch requires understanding the protocol specification, setting up the transport layer, defining tool schemas, handling errors correctly, and writing tests. The mcp-builder skill front-loads all of this knowledge so Claude Code produces correct server code on the first attempt. Instead of iterating through protocol misunderstandings, the agent follows a validated template that covers common patterns.

How to use

1. Add the mcp-builder skill to your Claude Code project. It is included as an official skill in Claude Code installations.

1. Ask Claude Code to build an MCP server:

Build an MCP server that connects to my PostgreSQL database and exposes query and schema inspection tools

1. Claude Code follows the skill's guidance to generate:

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

const server = new Server({
  name: 'postgres-mcp',
  version: '1.0.0'
}, {
  capabilities: { tools: {} }
});

server.setRequestHandler('tools/list', async () => ({
  tools: [
    {
      name: 'query',
      description: 'Execute a read-only SQL query',
      inputSchema: {
        type: 'object',
        properties: {
          sql: { type: 'string', description: 'SQL query to execute' }
        },
        required: ['sql']
      }
    }
  ]
}));

Example

// Tool handler with proper error handling
server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === 'query') {
    try {
      const result = await pool.query(args.sql);
      return { content: [{ type: 'text', text: JSON.stringify(result.rows) }] };
    } catch (error) {
      return { content: [{ type: 'text', text: `Query error: ${error.message}` }], isError: true };
    }
  }
});

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

Related on TokRepo

• MCP Postgres Integration -- PostgreSQL MCP server configuration
• MCP GitHub Integration -- GitHub MCP server for code operations

Common pitfalls

• MCP servers must handle errors gracefully with isError: true in the response. Throwing unhandled exceptions crashes the server and disconnects the client.
• Tool input schemas must use JSON Schema format. Missing required fields or incorrect types cause silent failures when the client validates inputs.
• The stdio transport reads from stdin and writes to stdout. Any console.log statements in your server code corrupt the protocol stream. Use stderr for debug logging.