MCP Server Writing

Purpose

Guide creation of production-ready Model Context Protocol (MCP) servers following official SDK patterns, security best practices, and real-world implementation patterns.

When to Use This Skill

Building a new MCP server from scratch
Adding tools, resources, or prompts to an existing MCP server
Choosing between TypeScript and Python implementations
Implementing proper error handling and validation for MCP tools
Setting up structured logging for MCP servers

When NOT to Use This Skill

Reviewing existing MCP code (use mcp-server-reviewing)
Building simple CLI tools that don't need LLM integration
Creating HTTP REST APIs (MCP uses JSON-RPC, not REST)
General TypeScript/Python development unrelated to MCP

Quick Decision: TypeScript vs Python

Factor	TypeScript	Python FastMCP
Type Safety	Excellent (Zod/Ajv)	Good (type hints)
Schema Validation	Built-in with Zod	Decorator-based
Prototyping Speed	Medium	Fast
Production Readiness	High	High
Ecosystem	Node.js, npm	pip, uv

Recommendation: Use TypeScript for production servers with complex schemas. Use Python FastMCP for rapid prototyping or when integrating with Python libraries.

Core Workflow

Step 1: Initialize Server

TypeScript:

typescript

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

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

Python FastMCP:

python

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-mcp-server", json_response=True)

Step 2: Define Tools with Input Schemas

Tools are functions the LLM can call. Always include:

Clear description explaining what the tool does
inputSchema with property descriptions
Validation before processing

TypeScript (Low-Level API):

typescript

import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  Tool,
} from "@modelcontextprotocol/sdk/types.js";

const TOOLS: Tool[] = [
  {
    name: "process_data",
    description:
      "Validates and transforms input data. Returns structured result with any validation errors.",
    inputSchema: {
      type: "object",
      properties: {
        data: {
          type: "string",
          description: "Raw data string to process",
        },
        format: {
          type: "string",
          enum: ["json", "csv", "xml"],
          description: "Expected input format",
        },
      },
      required: ["data", "format"],
    },
  },
];

server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: TOOLS }));

Python FastMCP:

python

@mcp.tool()
def process_data(data: str, format: str = "json") -> dict:
    """Validates and transforms input data.

    Args:
        data: Raw data string to process
        format: Expected input format (json, csv, xml)

    Returns:
        Structured result with validation errors if any
    """
    # Implementation here
    return {"success": True, "processed": data}

Step 3: Implement Tool Handler with Validation

Critical: Always validate inputs before processing. Use Ajv for TypeScript.

typescript

import Ajv from "ajv";

const ajv = new Ajv();
const validateProcessDataArgs = ajv.compile({
  type: "object",
  properties: {
    data: { type: "string" },
    format: { type: "string", enum: ["json", "csv", "xml"] },
  },
  required: ["data", "format"],
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "process_data") {
    // Validate inputs
    if (!validateProcessDataArgs(args)) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: "Validation failed",
              details: validateProcessDataArgs.errors,
              suggestion: "Check input parameters match the schema",
            }),
          },
        ],
        isError: true,
      };
    }

    // Process valid inputs
    const result = processData(args.data, args.format);
    return {
      content: [{ type: "text", text: JSON.stringify(result) }],
    };
  }

  return {
    content: [{ type: "text", text: `Unknown tool: ${name}` }],
    isError: true,
  };
});

Step 4: Add Resources (Optional)

Resources expose data the LLM can read. Use for configuration, status, or reference data.

TypeScript:

typescript

import {
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

server.setRequestHandler(ListResourcesRequestSchema, () => ({
  resources: [
    {
      uri: "config://settings",
      name: "Application Settings",
      description: "Current server configuration",
      mimeType: "application/json",
    },
  ],
}));

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  if (request.params.uri === "config://settings") {
    return {
      contents: [
        {
          uri: "config://settings",
          mimeType: "application/json",
          text: JSON.stringify({ theme: "dark", version: "1.0.0" }),
        },
      ],
    };
  }
  throw new Error(`Unknown resource: ${request.params.uri}`);
});

Python FastMCP:

python

@mcp.resource("config://settings")
def get_settings() -> str:
    """Current server configuration."""
    return json.dumps({"theme": "dark", "version": "1.0.0"})

Step 5: Add Prompts (Optional)

Prompts are reusable templates the LLM can request.

Python FastMCP:

python

@mcp.prompt()
def review_code(code: str, language: str = "python") -> str:
    """Generate a code review prompt."""
    return f"Please review this {language} code for best practices:\n\n{code}"

Step 6: Implement Structured Logging

Critical for MCP: Log to stderr, NEVER stdout. stdout is reserved for JSON-RPC.

typescript

// utils/logger.ts
class Logger {
  private log(level: string, message: string, context?: object): void {
    const entry = {
      timestamp: new Date().toISOString(),
      level,
      message,
      service: "my-mcp-server",
      ...context,
    };
    // CRITICAL: Use stderr, not stdout
    console.error(JSON.stringify(entry));
  }

  info(message: string, context?: object): void {
    this.log("INFO", message, context);
  }

  error(message: string, context?: object, error?: Error): void {
    this.log("ERROR", message, {
      ...context,
      error: error
        ? { name: error.name, message: error.message, stack: error.stack }
        : undefined,
    });
  }
}

export const logger = new Logger();

Step 7: Start the Server

TypeScript:

typescript

async function main(): Promise<void> {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  logger.info("MCP Server started", { transport: "stdio" });
}

main().catch((error) => {
  logger.error("Fatal error", {}, error);
  process.exit(1);
});

Python FastMCP:

python

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

Examples

Example 1: Tool with Validation Error Response

typescript

// Always return actionable suggestions with errors
if (!validateArgs(args)) {
  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          success: false,
          errors: [
            {
              field: "partner_id",
              message: "Invalid UUID format",
              suggestion: "Use format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            },
          ],
        }),
      },
    ],
    isError: true,
  };
}

Example 2: ReDoS Prevention

typescript

// Limit input length before regex processing
const MAX_INPUT_LENGTH = 50_000;

function safeInput(text: string): string {
  return text.length > MAX_INPUT_LENGTH
    ? text.slice(0, MAX_INPUT_LENGTH)
    : text;
}

// Use in tool handlers
const safeText = safeInput(args.text);
const matches = safeText.match(/pattern/);

Example 3: Dynamic Resource Template

python

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """Get user profile by ID."""
    user = fetch_user(user_id)
    return json.dumps({"id": user_id, "name": user.name, "role": user.role})

Validation Checklist

Before deploying your MCP server:

All tools have clear description fields
All input schema properties have description
Input validation runs before any processing
Error responses include isError: true flag
Error messages include actionable suggestion
Logging goes to stderr (not stdout)
Input length limited before regex processing (ReDoS prevention)
No hardcoded secrets in code
Environment variables used for configuration

Common Patterns

Pattern: Structured Error Response

typescript

interface ToolError {
  field: string;
  message: string;
  suggestion: string;
}

function createErrorResponse(errors: ToolError[]) {
  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({ success: false, errors }),
      },
    ],
    isError: true,
  };
}

Pattern: Tool Invocation Logging

typescript

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  const startTime = Date.now();

  logger.info("Tool invocation started", {
    tool: name,
    args_keys: Object.keys(args || {}),
  });

  try {
    const result = await handleTool(name, args);
    logger.info("Tool invocation completed", {
      tool: name,
      duration_ms: Date.now() - startTime,
    });
    return result;
  } catch (error) {
    logger.error(
      "Tool invocation failed",
      {
        tool: name,
        duration_ms: Date.now() - startTime,
      },
      error,
    );
    throw error;
  }
});

Troubleshooting

Issue: Server hangs or produces garbled output

Cause: Logging to stdout instead of stderr Solution: Change all console.log() to console.error() for logging

Issue: Validation errors not shown to LLM

Cause: Missing isError: true in response Solution: Add isError: true to all error responses

Issue: Complex regex causes timeouts

Cause: ReDoS vulnerability with unbounded input Solution: Limit input length with safeInput() function

Related Skills

mcp-server-reviewing - Audit MCP servers for best practices
security-scan - Check for secrets before commits
quality-check - Run linting and formatting

Resources

MCP TypeScript SDK
MCP Python SDK
MCP Best Practices
See REFERENCE.md for complete templates and advanced patterns

Search AI Tools

mcp-server-writing

Install this agent skill to your Project

SKILL.md

MCP Server Writing

Purpose

When to Use This Skill

When NOT to Use This Skill

Quick Decision: TypeScript vs Python

Core Workflow

Step 1: Initialize Server

Step 2: Define Tools with Input Schemas

Step 3: Implement Tool Handler with Validation

Step 4: Add Resources (Optional)

Step 5: Add Prompts (Optional)

Step 6: Implement Structured Logging

Step 7: Start the Server

Examples

Example 1: Tool with Validation Error Response

Example 2: ReDoS Prevention

Example 3: Dynamic Resource Template

Validation Checklist

Common Patterns

Pattern: Structured Error Response

Pattern: Tool Invocation Logging

Troubleshooting

Issue: Server hangs or produces garbled output

Issue: Validation errors not shown to LLM

Issue: Complex regex causes timeouts

Related Skills

Resources