mcp-builder

xenitV1's avatarfrom xenitV1

MCP (Model Context Protocol) server creation for integrating external services with AI.

⭐62stars🔀15forks📁View on GitHub🕐Updated Jan 2, 2026
[Developer Tools]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework and best practices for building Model Context Protocol (MCP) servers. It streamlines the process of integrating external services, databases, and tools with AI models by providing clear guidelines on tool design, resource patterns, and secure architecture, essential for developers creating advanced AI agent ecosystems.

Use Cases

  • 1. Custom Tool Development: Designing and implementing bespoke MCP tools that allow AI agents to interact with proprietary internal APIs and legacy systems.
  • 2. Data Integration: Creating standardized resource patterns to expose local or cloud-based datasets to LLMs in a structured, searchable, and secure format.
  • 3. Agent Infrastructure Optimization: Applying best practices for error handling, multimodal support, and transport types (Stdio/SSE) to ensure robust and reliable AI-to-tool communication.
namemcp-builder
descriptionMCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices.
allowed-toolsRead, Write, Edit, Glob, Grep

MCP Builder

Principles for building MCP servers.

1. MCP Overview

What is MCP?

Model Context Protocol - standard for connecting AI systems with external tools and data sources.

Core Concepts

Concept Purpose
Tools Functions AI can call
Resources Data AI can read
Prompts Pre-defined prompt templates

2. Server Architecture

Project Structure

my-mcp-server/
├── src/
│   └── index.ts      # Main entry
├── package.json
└── tsconfig.json

Transport Types

Type Use
Stdio Local, CLI-based
SSE Web-based, streaming
WebSocket Real-time, bidirectional

3. Tool Design Principles

Good Tool Design

Principle Description
Clear name Action-oriented (get_weather, create_user)
Single purpose One thing well
Validated input Schema with types and descriptions
Structured output Predictable response format

Input Schema Design

Field Required?
Type Yes - object
Properties Define each param
Required List mandatory params
Description Human-readable

4. Resource Patterns

Resource Types

Type Use
Static Fixed data (config, docs)
Dynamic Generated on request
Template URI with parameters

URI Patterns

Pattern Example
Fixed docs://readme
Parameterized users://{userId}
Collection files://project/*

5. Error Handling

Error Types

Situation Response
Invalid params Validation error message
Not found Clear "not found"
Server error Generic error, log details

Best Practices

  • Return structured errors
  • Don't expose internal details
  • Log for debugging
  • Provide actionable messages

6. Multimodal Handling

Supported Types

Type Encoding
Text Plain text
Images Base64 + MIME type
Files Base64 + MIME type

7. Security Principles

Input Validation

  • Validate all tool inputs
  • Sanitize user-provided data
  • Limit resource access

API Keys

  • Use environment variables
  • Don't log secrets
  • Validate permissions

8. Configuration

Claude Desktop Config

Field Purpose
command Executable to run
args Command arguments
env Environment variables

9. Testing

Test Categories

Type Focus
Unit Tool logic
Integration Full server
Contract Schema validation

10. Best Practices Checklist

  • Clear, action-oriented tool names
  • Complete input schemas with descriptions
  • Structured JSON output
  • Error handling for all cases
  • Input validation
  • Environment-based configuration
  • Logging for debugging

Remember: MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.