Building Your First MCP Server in TypeScript

Overview

An MCP server acts as the translation layer between an AI runtime and real application capabilities. The minimum useful server usually exposes tools, resources, and a clean error model.

Prerequisites

• TypeScript project setup
• basic understanding of JSON-RPC style request/response flows
• clear boundaries around what the AI is allowed to do

Server skeleton

1export function createServer() {
2  return {
3    name: 'knowledge-server',
4    version: '1.0.0',
5    tools: [],
6    resources: [],
7  }
8}

Tool design rules

• validate all inputs
• return structured outputs
• make failure states explicit
• keep side effects isolated

Error handling

When a tool fails, the AI should receive enough structure to recover gracefully instead of guessing.

1type ToolError = {
2  code: string
3  message: string
4  retryable: boolean
5}

Summary

The first production habit to build is strict contracts. A good MCP server is predictable long before it is feature-rich.