mcpskills.net — Curated AI Skills, MCPs & Agents

mcpskills.net

Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools.

High-Level Workflow

Phase 1: Deep Research and Planning

Understand Modern MCP Design

API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage with specialized workflow tools. When uncertain, prioritize comprehensive API coverage.

Tool Naming and Discoverability: Clear, descriptive tool names help agents find the right tools quickly. Use consistent prefixes and action-oriented naming.

Context Management: Agents benefit from concise tool descriptions and the ability to filter/paginate results.

Actionable Error Messages: Error messages should guide agents toward solutions with specific suggestions and next steps.

Study MCP Protocol Documentation

Navigate the MCP specification starting with the sitemap: https://modelcontextprotocol.io/sitemap.xml

Key pages to review:

Specification overview and architecture
Transport mechanisms (streamable HTTP, stdio)
Tool, resource, and prompt definitions

Plan Your Implementation

Recommended stack:

Language: TypeScript (high-quality SDK support)
Transport: Streamable HTTP for remote servers, stdio for local servers

Phase 2: Implementation

Set Up Project Structure

TypeScript project with proper tsconfig.json
Zod schemas for input validation
Proper error handling

Implement Core Infrastructure

Create shared utilities:

API client with authentication
Error handling helpers
Response formatting (JSON/Markdown)
Pagination support

Implement Tools

For each tool:

Input Schema: Use Zod with constraints and clear descriptions
Output Schema: Define outputSchema where possible
Tool Description: Concise summary of functionality
Implementation: Async/await, proper error handling, pagination support
Annotations: readOnlyHint, destructiveHint, idempotentHint, openWorldHint

Phase 3: Review and Test

Code Quality

Review for:

No duplicated code (DRY principle)
Consistent error handling
Full type coverage
Clear tool descriptions

Build and Test

npm run build
npx @modelcontextprotocol/inspector

Phase 4: Create Evaluations

Create comprehensive evaluations to test effectiveness:

Tool Inspection: List available tools
Content Exploration: Use READ-ONLY operations
Question Generation: Create 10 complex, realistic questions
Answer Verification: Solve each question yourself

Each question must be:

Independent
Read-only
Complex (requiring multiple tool calls)
Realistic
Verifiable
Stable