MCP Server Development

Create MCP servers that enable LLMs to interact with external services through well-designed tools.

Development Phases

Phase 1: Research & Planning

Understand the API:

Review service's API documentation
Identify key endpoints, auth requirements, data models
Use Context7 or Firecrawl as needed

Tool Selection:

Prioritize comprehensive API coverage over workflow shortcuts
List endpoints to implement, starting with most common operations
Balance single-operation tools (flexible) vs workflow tools (convenient)

Load Framework Docs:

TypeScript SDK: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
Python SDK: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

Phase 2: Implementation

Recommended Stack:

Language: TypeScript (best SDK support, good for agent-generated code)
Transport: Streamable HTTP for remote, stdio for local

Project Structure (TypeScript):

my-mcp-server/
├── src/
│   ├── index.ts          # Server entry point
│   ├── tools/            # Tool implementations
│   └── utils/            # Shared utilities
├── package.json
└── tsconfig.json

Tool Implementation Pattern:

server.registerTool({
  name: "service_operation",
  description: "Concise description of what this does",
  inputSchema: z.object({
    param: z.string().describe("What this parameter is for"),
    optional: z.number().optional().describe("Optional config"),
  }),
  outputSchema: z.object({
    result: z.string(),
    metadata: z.object({ count: z.number() }),
  }),
  annotations: {
    readOnlyHint: true,      // Doesn't modify state
    destructiveHint: false,  // Doesn't delete data
    idempotentHint: true,    // Safe to retry
    openWorldHint: false,    // Bounded result set
  },
  async execute({ param, optional }) {
    // Implementation with proper error handling
    const result = await apiClient.doOperation(param);
    return {
      structuredContent: { result: result.data, metadata: { count: 1 } },
      content: [{ type: "text", text: `Operation completed: ${result.data}` }],
    };
  },
});

Phase 3: Review & Test

Code Quality:

No duplicated code (DRY principle)
Consistent error handling with actionable messages
Full type coverage
Clear tool descriptions

Testing:

# TypeScript - verify compilation
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

# Python - verify syntax
python -m py_compile your_server.py

Phase 4: Evaluations

Create 10 evaluation questions to test effectiveness:

Question Requirements:

Independent: Not dependent on other questions
Read-only: Only non-destructive operations
Complex: Require multiple tool calls
Realistic: Based on real use cases
Verifiable: Single, clear answer
Stable: Answer won't change over time

Format:

<evaluation>
  <qa_pair>
    <question>Find all repositories with more than 100 stars 
    that were created this year. What is the total star count?</question>
    <answer>1547</answer>
  </qa_pair>
</evaluation>

Tool Design Best Practices

Naming Convention

Use consistent prefixes with action-oriented names:

✅ github_create_issue, github_list_repos, github_get_user
✅ slack_send_message, slack_list_channels
❌ createIssue, listRepos (inconsistent)
❌ issue, repos (not action-oriented)

Descriptions

// ❌ Too vague
description: "Gets data from the API"

// ✅ Specific and helpful
description: "Retrieves repository metadata including stars, forks, and last commit date. Returns structured data for analysis."

Error Messages

Guide agents toward solutions:

// ❌ Generic error
throw new Error("Request failed");

// ✅ Actionable error
throw new Error(
  "Repository not found. Verify the owner/repo format (e.g., 'anthropics/sdk'). " +
  "Use github_search_repos to find the correct repository name."
);

Pagination

Support filtering and pagination for list operations:

inputSchema: z.object({
  query: z.string().optional().describe("Filter results"),
  limit: z.number().default(20).describe("Max results to return"),
  cursor: z.string().optional().describe("Pagination cursor from previous response"),
}),

Output Schemas

Define structured output for better agent understanding:

outputSchema: z.object({
  items: z.array(z.object({
    id: z.string(),
    name: z.string(),
    metadata: z.record(z.unknown()),
  })),
  nextCursor: z.string().optional(),
  totalCount: z.number(),
}),

Tool Annotations Reference

Annotation	Description	Example
`readOnlyHint`	Tool doesn't modify external state	List operations, queries
`destructiveHint`	Tool permanently deletes data	Delete operations
`idempotentHint`	Multiple calls produce same result	Get by ID, upsert
`openWorldHint`	Results may change between calls	Real-time data feeds

Common Patterns

API Client Setup

const client = {
  baseUrl: process.env.API_URL,
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
  
  async request<T>(path: string, options?: RequestInit): Promise<T> {
    const response = await fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: { ...this.headers, ...options?.headers },
    });
    if (!response.ok) {
      throw new Error(`API error: ${response.status} - ${await response.text()}`);
    }
    return response.json();
  },
};

Batch Operations

// Allow operating on multiple items efficiently
inputSchema: z.object({
  ids: z.array(z.string()).max(100).describe("IDs to process (max 100)"),
}),

Dry Run Support

inputSchema: z.object({
  changes: z.array(ChangeSchema),
  dryRun: z.boolean().default(false).describe("Preview changes without applying"),
}),

mcp-development