mcp-patterns_skill

Overview

This skill provides practical Model Context Protocol (MCP) server patterns for building integrations with Claude Code. It bundles example server code, project layout guidance, and configuration snippets to help you expose tools and resources to Claude via MCP. Use these patterns to implement reliable tool handlers, resource endpoints, auth, and state management for production or development servers.

How this skill works

The skill inspects common MCP server workflows and gives ready-to-use patterns: tool registration (list_tools), tool invocation (call_tool), and resource handling. It includes examples for running a Python MCP server over stdio or via a process manager (uv), plus recommended project layout, configuration fragments for Claude Desktop, and quick-reference patterns for validation, auth, caching, and testing. Common issues and solutions are documented to speed troubleshooting.

When to use it

• Building a custom MCP server to expose tools to Claude Code
• Validating and sanitizing tool inputs before execution
• Adding resources (static or dynamic) accessible to the model
• Implementing auth using environment variables or token refresh
• Persisting state or caching tool results for faster responses

Best practices

• Define strict input schemas (JSON Schema / Pydantic) for each tool to avoid runtime errors
• Return well-formed MCP content arrays from call_tool (text or structured blocks)
• Run the server under a supervisor (uv or similar) for stable process management
• Store secrets in environment variables referenced by your MCP config, not in shell profiles
• Add timeouts and async patterns for network calls to prevent server-wide stalls

Example use cases

• Search tool: register a search tool with query input and return formatted results
• CRUD tools: expose create/read/update/delete handlers for an internal DB via multiple tools
• Resource exposure: provide static config or dynamic DB-backed resources to the model
• Auth wrapper: implement API-key or OAuth token refresh and surface tokens as resources
• Testing: write pytest-async tests for tool handlers and a manual script for quick validation