A methodology for systematically designing, implementing, testing, and deploying Model Context Protocol (MCP) servers, enabling AI assistants to connect to external tools and data sources.
Tasks
Design an MCP server by mapping operations to the correct primitives: Tools for actions with side effects, Resources for read-only data identified by URIs, and Prompts for predefined interaction templates.
Implement TypeScript or Python MCP servers following the specified project structure, using snake_case naming for tools, defining parameters with type constraints and descriptions, and returning structured JSON or Markdown content.
Validate inputs using Zod or Pydantic at the schema level, apply business-level validation inside handlers, and wrap external calls in try/catch blocks to return actionable error messages with the isError flag.
Debug the server using the MCP Inspector (npx @modelcontextprotocol/inspector node dist/index.js) and test it manually before connecting it to a real AI client.
Inputs
Operations requiring side effects to be mapped to Tools
Read-only data sources identified by URIs to be mapped to Resources
Predefined interaction templates to be mapped to Prompts
Tool parameters with type constraints, descriptions, and optional default values
Outputs
MCP server source code structured for TypeScript or Python
Structured JSON or Markdown responses using the content: [{ type: "text", text: "..." }] format
Error messages flagged with isError: true containing actionable information
Client configuration JSON examples for deployment
Limitations and checks
MCP uses stdio for communication, so console.log cannot be used as it breaks the protocol stream.
Servers must register tools and resources before calling server.connect().
Tool descriptions must clearly state purpose, return content, and limitations, as AI assistants rely solely on them for tool selection.
Confirm the correct MCP primitive is chosen: Tools for execution, Resources for data reading, and Prompts for interaction guidance.
Verify all external calls are wrapped in try/catch blocks with timeouts and that errors are returned with isError: true.
Ensure no console.log is used in stdio communication and that logging is done via stderr or server.sendLoggingMessage.
Validate that sensitive data such as API keys is passed via environment variables and not hardcoded.
Check that the deployment package includes a README with installation instructions and a client configuration JSON example.