mcp-developer_skill

Overview

This skill is a practical, Python-focused guide for building Model Context Protocol (MCP) servers. It covers server setup, tool definitions and handlers, stdio and SSE transport modes, testing patterns, and common error resolution. The content emphasizes robust input validation, async patterns, and resource management to create reliable MCP services.

How this skill works

The guide explains how an MCP server exposes tools via JSON-RPC 2.0 over stdio or SSE and how the server registers tool listings and call handlers. It shows how to initialize the Server, define tools with JSON Schema inputSchema, implement async handlers that validate inputs and return typed TextContent results, and run the server using appropriate read/write streams. It also details testing strategies, error handling, caching, and cleanup patterns for production-ready behavior.

When to use it

• Creating a new MCP server from scratch in Python
• Implementing or updating tool definitions and call handlers
• Setting up stdio-based local MCP integrations
• Running MCP over HTTP using Server-Sent Events (SSE)
• Writing unit and end-to-end tests for MCP tools
• Debugging communication, type validation, and import errors

Best practices

• Validate all inputs: check required params, use isinstance() and JSON Schema types
• Keep handlers async and non-blocking; use pytest-asyncio for tests
• Log errors to stderr, wrap user-facing issues in RuntimeError for clarity
• Cache expensive resources with lazy initialization and reuse across calls
• Clean up temporary files and close handles in finally blocks
• Mock external dependencies in unit tests and cover both success and error paths

Example use cases

• A local CLI tool that exposes OCR or image-processing functions to an agent via stdio
• A web-hosted MCP server using SSE to let remote clients invoke model-context tools
• Testing tool input validation and error paths with pytest async tests
• Implementing multiple-result responses by returning lists of TextContent
• Debugging 'Unknown tool' and 'Missing required argument' errors during integration