Building & Debugging Model Context Protocol (MCP) Servers: A Developer’s Blueprint

As Large Language Model (LLM) agents evolve from chat interfaces into autonomous software tools, providing safe, standardized access to local environments, databases, and third-party APIs has become a core engineering challenge. Anthropic's Model Context Protocol (MCP) establishes an open standard for connecting AI clients (such as Claude Desktop, Cursor, or custom agents) to external context sources and execution tools seamlessly.

1. What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open specification based on client-server architecture. An MCP Client (e.g. Claude Desktop application) establishes connection streams to one or more MCP Servers (local binaries or remote web servers) that expose tools, resources, and prompt templates.

2. Transport Layer: Stdio vs SSE

MCP relies on JSON-RPC 2.0 for request/response serialization. The protocol defines two standard transport mechanisms:

• Standard I/O (Stdio): Ideal for local tools. The host process launches the MCP server binary as a child process and communicates via standard input (stdin) and standard output (stdout).
• Server-Sent Events (SSE): Ideal for remote cloud servers. The client opens an HTTP GET connection to receive real-time server events, while RPC requests are sent via HTTP POST messages.

3. Core Primitives: Tools, Prompts & Resources

An MCP server declares its capabilities during the initial handshake. The three fundamental primitives are:

1. Tools (Executable Functions): Methods exposed to the AI model that take structured parameters (validated via JSON Schema) and return execution results (text, images, or error objects).
2. Resources (Context Data): Static or dynamic data items (file paths, database records, API responses) that clients can read to supply context to the LLM.
3. Prompts (Reusable Templates): Pre-built prompt workflows and slash commands exposed directly to user interfaces.

4. Step-by-Step MCP Server Implementation

Here is how to create a minimal TypeScript MCP server using the official @modelcontextprotocol/sdk package:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

// Initialize MCP Server instance
const server = new Server(
  { name: "devbuildtool-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Register available tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "calculate_aspect_ratio",
      description: "Calculate proportional target width or height for web layouts",
      inputSchema: {
        type: "object",
        properties: {
          width: { type: "number", description: "Source width in pixels" },
          height: { type: "number", description: "Source height in pixels" },
          targetWidth: { type: "number", description: "Desired target width" }
        },
        required: ["width", "height", "targetWidth"]
      }
    }
  ]
}));

// Handle tool execution requests
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_aspect_ratio") {
    const { width, height, targetWidth } = request.params.arguments as any;
    const targetHeight = Math.round(targetWidth * (height / width));
    
    return {
      content: [
        { type: "text", text: `Target Dimensions: ${targetWidth}x${targetHeight}px` }
      ]
    };
  }
  throw new Error("Tool not found");
});

// Connect stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);

5. Configuring Claude Desktop & Cursor

To connect your local MCP server to Claude Desktop, edit the configuration file located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-dev-tools": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

6. Debugging & Inspector Workflows

Because stdio transport uses standard input/output for JSON-RPC payloads, never use console.log() inside stdio MCP servers. Printing raw text lines directly to stdout corrupts the JSON-RPC stream and causes the host client to drop the connection.

Always use console.error() for debug logging or use the official `@modelcontextprotocol/inspector` CLI tool to test tool registration interactively in your browser.