mcp-builder_skill

Overview

This skill explains principles for building MCP (Model Context Protocol) servers, focusing on tool design, resource patterns, error handling, security, and testing. It condenses architecture guidance and practical patterns for TypeScript-based MCP servers. The guidance emphasizes clarity, schema-driven inputs, and predictable outputs to make tools reliably usable by AI systems.

How this skill works

The skill inspects core MCP concepts: tools (callable functions), resources (readable data URIs), and prompts (templates). It lays out server transport options (stdio, SSE, WebSocket), recommended project layout, input/output schema conventions, and resource URI patterns. It also covers error handling, multimodal payload encoding, configuration, security measures, and testing strategies.

When to use it

• Designing a new MCP server or refactoring an existing one
• Defining tools and input/output schemas for AI integrations
• Choosing transport and resource URI patterns for clients
• Implementing secure input validation and secret handling
• Establishing testing and contract validation for MCP endpoints

Best practices

• Name tools with clear, action-oriented verbs and give each tool one focused responsibility
• Define complete input schemas: types, required fields, and human descriptions
• Return structured, predictable JSON outputs and document response shape
• Validate and sanitize all inputs; never log secrets or internal details
• Use environment variables for sensitive config and limit resource access by permissions
• Log actionable errors for debugging and return safe, user-facing messages

Example use cases

• Create a get_weather tool with a validated location schema and structured forecast output
• Serve project documents via URIs like docs://readme and parameterized URIs like users://{userId}
• Stream model responses to web clients over SSE or support interactive sessions over WebSocket
• Expose image and file resources as Base64 with MIME type metadata for multimodal tools
• Run unit, integration, and contract tests to ensure schemas and transports behave as expected