MCP Builder

MCP Server Development Guide

Build high-quality MCP servers that enable LLMs to interact with external services

Staleness Watch: See EXTERNAL-API-REGISTRY.md for source URLs and recheck cadence

The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.

When to Build vs Use Existing

Microsoft MCP Servers

Before building custom, check if Microsoft already provides one:

Decision Matrix

Server Types

Phase 1: Research and Planning

1.1 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 (e.g., github_create_issue, github_list_repos) and action-oriented naming.

Context Management: Design tools that return focused, relevant data. 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.

1.2 Study MCP Protocol Documentation

Start 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

1.3 Select Language and Transport

Language Selection:

Transport Selection:

Phase 2: Implementation

TypeScript Server (Recommended)

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});

// Register a tool with Zod schema
server.tool(
  "get_weather",
  "Get current weather for a city",
  { city: z.string().describe("City name") },
  async ({ city }) => ({
    content: [{ type: "text", text: JSON.stringify({ city, temp: "72°F" }) }],
  })
);

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

Python Server (FastMCP)

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field

mcp = FastMCP("my-mcp-server")

class WeatherParams(BaseModel):
    city: str = Field(description="City name")

@mcp.tool(description="Get current weather for a city")
async def get_weather(params: WeatherParams) -> dict:
    return {"city": params.city, "temp": "72°F"}

if __name__ == "__main__":
    mcp.run()

C#/.NET Server

using Microsoft.Mcp.Core;

var server = new McpServerBuilder()
    .WithName("my-mcp-server")
    .WithVersion("1.0.0")
    .AddTool("get_weather", "Get current weather", async (string city) =>
        new { city, temp = "72°F" })
    .Build();

await server.RunAsync();

Tool Design Best Practices

Input Schema

• Use Zod (TypeScript) or Pydantic (Python) for validation
• Include constraints and clear descriptions
• Add examples in field descriptions

Output Schema

• Define outputSchema where possible for structured data
• Use structuredContent in tool responses (TypeScript SDK feature)
• Helps clients understand and process tool outputs

Annotations

Implementation Patterns

// Good: Async, error handling, pagination
server.tool(
  "list_items",
  "List items with pagination",
  {
    page: z.number().default(1),
    limit: z.number().max(100).default(20),
  },
  async ({ page, limit }) => {
    try {
      const items = await api.listItems({ page, limit });
      return {
        content: [{
          type: "text",
          text: JSON.stringify({ items, page, hasMore: items.length === limit }),
        }],
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error: ${error.message}. Try: check API key, verify endpoint, reduce page size.`,
        }],
        isError: true,
      };
    }
  }
);

Phase 3: Testing

Build and Verify

TypeScript:

npm run build
npx @modelcontextprotocol/inspector ./dist/server.js

Python:

python -m py_compile your_server.py
npx @modelcontextprotocol/inspector -- python your_server.py

MCP Inspector

Interactive debugging for any MCP server:

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

Code Quality Checklist

• No duplicated code (DRY principle)
• Consistent error handling with actionable messages
• Full type coverage
• Clear tool descriptions
• Pagination support where applicable
• Proper async/await for I/O operations

Phase 4: Create Evaluations

Evaluation Purpose

Test whether LLMs can effectively use your MCP server to answer realistic, complex questions.

Create 10 Evaluation Questions

1. Tool Inspection: List available tools and understand capabilities
2. Content Exploration: Use READ-ONLY operations to explore data
3. Question Generation: Create 10 complex, realistic questions
4. Answer Verification: Solve each question yourself to verify answers

Evaluation Requirements

Each question must be:

• Independent: Not dependent on other questions
• Read-only: Only non-destructive operations required
• Complex: Requiring multiple tool calls and deep exploration
• Realistic: Based on real use cases humans would care about
• Verifiable: Single, clear answer that can be verified by string comparison
• Stable: Answer won't change over time

Output Format

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined?</question>
    <answer>3</answer>
  </qa_pair>
  <!-- More qa_pairs... -->
</evaluation>

Common Issues

Related Skills

This skill complements:

• mcp-development — Core MCP protocol patterns and architecture
• azure-architecture-patterns — When building Azure-integrated MCP servers
• testing-strategies — For comprehensive MCP server testing

References

• MCP Protocol Specification
• TypeScript SDK
• Python SDK
• MCP Servers Directory
• MCP Inspector