Skip to content

MustafaKucukcoskun/Refine-agent-kit / .agents/skills/mcp-builder

mcp-builder

Verified

MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices. Use when building MCP servers, creating AI tools, or exposing resources via Model Context Protocol.

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

ConceptPurpose
ToolsFunctions AI can call
ResourcesData AI can read
PromptsPre-defined prompt templates

2. Server Architecture

Project Structure

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

Transport Types

TypeUse
StdioLocal, CLI-based
SSEWeb-based, streaming
WebSocketReal-time, bidirectional

3. Tool Design Principles

Good Tool Design

PrincipleDescription
Clear nameAction-oriented (get_weather, create_user)
Single purposeOne thing well
Validated inputSchema with types and descriptions
Structured outputPredictable response format

Input Schema Design

FieldRequired?
TypeYes - object
PropertiesDefine each param
RequiredList mandatory params
DescriptionHuman-readable

4. Resource Patterns

Resource Types

TypeUse
StaticFixed data (config, docs)
DynamicGenerated on request
TemplateURI with parameters

URI Patterns

PatternExample
Fixeddocs://readme
Parameterizedusers://{userId}
Collectionfiles://project/*

5. Error Handling

Error Types

SituationResponse
Invalid paramsValidation error message
Not foundClear "not found"
Server errorGeneric error, log details

Best Practices

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

6. Multimodal Handling

Supported Types

TypeEncoding
TextPlain text
ImagesBase64 + MIME type
FilesBase64 + 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

FieldPurpose
commandExecutable to run
argsCommand arguments
envEnvironment variables

9. Testing

Test Categories

TypeFocus
UnitTool logic
IntegrationFull server
ContractSchema 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.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall