mcp-server-design

MCP Server Design

Overview

This skill provides best practices for designing MCP (Model Context Protocol) servers that work effectively with LLM agents. The key insight: design for agents, not automation. LLMs are human-like thinkers, not API consumers.

Core Philosophy

Design for Agents, Not Automation

Traditional API design optimizes for programmatic access with granular endpoints. MCP tool design should optimize for how LLMs think and reason:

• LLMs are human-like thinkers: They understand intent, context, and purpose
• Tools should be tasks, not endpoints: Shape tools around what users want to accomplish
• Reduce cognitive load: Fewer, more purposeful tools beat many granular ones

The Three Pillars

1. Give everything ready: Provide complete, actionable information
2. Reduce effort: Minimize steps needed to accomplish tasks
3. Reduce paths: Limit decision branches the LLM must navigate

Tool Design Principles

1. Purpose-Built Tools Over Generic Wrappers

Anti-pattern: Wrapping every API endpoint as a tool

// Bad: Generic database tools
// src/tools/run-sql.ts
// src/tools/list-tables.ts
// src/tools/describe-table.ts

Best practice: Design tools around user tasks

// Good: Task-oriented tools
// src/tools/prepare-database-migration.ts
import { z } from "zod";
import type { ToolMetadata } from "xmcp";

export const schema = {
  description: z.string().describe("What database changes are needed"),
};

export const metadata: ToolMetadata = {
  name: "prepare-database-migration",
  description: "Design a database change with safety checks and reviewed migration plan",
};

// src/tools/analyze-slow-queries.ts
// src/tools/create-backup.ts

2. Minimize Tool Count

LLMs struggle with long tool lists. Each additional tool:

• Increases selection confusion
• Adds tokens to every request
• Dilutes the purpose of each tool

Guidelines:

• Start with 5-10 core tools
• Add tools only when evals show they're needed
• Combine related operations when sensible