Build your first MCP server in TypeScript: the 2026 setup that takes 30 minutes.

Build your first MCP server in TypeScript: the 2026 setup that takes 30 minutes.

The promise of AI agents seamlessly interacting with your local data and tools has long felt like a distant future. Proprietary integrations and fragmented ecosystems made true interoperability a developer's nightmare. But what if you could bridge this gap, connecting your AI assistant to your local environment in less than an hour? With the Model Context Protocol (MCP) and TypeScript, that future is firmly in 2026, and building your first server is surprisingly straightforward.

Imagine your AI model querying your local SQLite database, managing your files, or even interacting with your development tools, all without cumbersome copy-pasting or custom API wrangling. This isn't science fiction; it's the reality enabled by MCP, an open standard that is rapidly becoming the universal language for AI-to-tool communication. This guide will walk you through setting up your first MCP server in TypeScript, demonstrating how you can achieve powerful AI integration in approximately 30 minutes.

The Dawn of Universal AI Integration: What is Model Context Protocol (MCP)?

Before MCP, the landscape of AI-to-tool integration was a wild west of custom solutions. OpenAI offered "function calling," Anthropic had "tool use," and various platforms rolled out their unique plugin formats. This fragmented approach led to an "N×M" data integration problem, where developers had to build bespoke connectors for every AI model and external system combination.

Enter the Model Context Protocol (MCP), an open standard and open-source framework introduced by Anthropic in November 2024. MCP was designed to standardize how large language models (LLMs) integrate and share data with external tools, systems, and data sources. It acts as a universal bridge, allowing AI to move beyond static knowledge and become a dynamic agent capable of retrieving current information and performing actions.

The adoption of MCP has been swift and significant. OpenAI officially embraced the protocol in March 2025, integrating it across its products, including the ChatGPT desktop app by September 2025. Notably, OpenAI even deprecated its Assistants API in favor of MCP, with a sunset planned for mid-2026, solidifying MCP's position as a cross-provider standard. Google DeepMind and Microsoft have also adopted MCP, with Microsoft announcing an early preview of Windows 11 embracing the protocol at Microsoft Build 2025.

At its core, MCP simplifies AI interaction through three key primitives:

Resources: Read-only data that the AI model can fetch on demand, such as database schemas, file contents, or API responses. Tools: Functions the AI model can call with structured arguments to perform actions, like running a query, sending an email, or converting data. Prompts: Reusable prompt templates that the client can surface to the user, streamlining common workflows.

This tutorial focuses on building tools and resources, which form the backbone of most practical MCP server implementations.

Building Your First MCP Server: The 30-Minute TypeScript Setup

Let's dive into the practical steps to get your TypeScript MCP server up and running. This setup leverages Node.js and the official MCP SDK, providing a robust foundation for your AI integrations.

1. Project Setup: Laying the Foundation (5 minutes) First, ensure you have Node.js installed. As of May 2026, Node.js 26.2.0 is the current stable release, while Node.js 24.16.0 is the latest Long Term Support (LTS) version. Node.js 18 or higher is generally recommended for modern projects. Open your terminal and execute the following commands: mkdir my-mcp-server cd my-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript @types/node mkdir src touch src/index.ts

Here's a breakdown:

`npm init -y`: Initializes a new Node.js project, creating a `package.json` file. `@modelcontextprotocol/sdk`: This is the official SDK for interacting with the Model Context Protocol. The version available on npm as of May 2026 is 1.11.x. `zod`: A powerful TypeScript-first schema validation library. Zod allows you to define clear, reusable schemas for your data and ensures that your data matches those schemas at runtime, inferring TypeScript types directly from your schemas. This is crucial for defining the structured inputs and outputs of your AI tools. `typescript` and `@types/node`: Essential for TypeScript development in Node.js, providing type definitions.

Next, update your `package.json` file with these fields to enable ES modules and define build/start scripts: { "type": "module", "scripts": { "build": "tsc", "start": "node build/index.js" } }

Create a `tsconfig.json` file in your project root for TypeScript configuration: { "compilerOptions": { "target": "ES2022", "module": "Node16", "moduleResolution": "Node16", "outDir": "./build", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true }, "include": ["src/**/*"], "exclude": ["node_modules"] }

This configuration specifies modern JavaScript targets, Node.js module resolution, output directories, and strict type checking, which are best practices for TypeScript projects.

2. Implementing Your First Tool (10 minutes) A tool is a function your AI model can call. You define its name, a descriptive explanation, its input schema, and the handler function that executes the logic. The model uses the description and schema to determine when and how to invoke it. Add the following code to `src/index.ts` to create a server with a simple tool that converts a hexadecimal color code to its RGB components: // src/index.ts 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: "color-tools", version: "1.0.0", });

server.tool( "hex_to_rgb", "Convert a hex color string to RGB components. Input must include the leading #.", { hex: z.string().regex(/^#[0-9a-fA-F]{6}$/, "Must be a 6-digit hex color, e.g. #ff5733"), }, async ({ hex }) => { const r = parseInt(hex.slice(1, 3), 16); const g = parseInt(hex.slice(3, 5), 16); const b = parseInt(hex.slice(5, 7), 16); return { content: [ { type: "text", text: JSON.stringify({ hex, r, g, b }), }, ], }; }, );

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

Key aspects of this tool:

The description string is critical. It's what the AI model reads to decide if and how to use your tool. Be clear and concise, as you would for JSDoc comments. The Zod schema defines the expected input. The SDK converts this into a JSON Schema, which the client sends to the model. Keeping schemas tight with only necessary fields improves reliability. The return value must be an object with a `content` array. For structured data, return JSON as a string within a `text` item.

Build and test your server locally: npm run build echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node build/index.js

You should see a JSON-RPC response listing `hex_to_rgb`, confirming your server is operational and responding to requests.

3. Implementing a Resource (8 minutes) Resources allow your AI model to pull read-only data on demand. A common use case is exposing a database schema so the model understands the data structure before attempting to write queries. Add the following resource definition before the `transport` setup in `src/index.ts`: server.resource( "db-schema", "sqlite:///local.db", async (uri) => { // In a real server, read this from your database const schema = ` CREATE TABLE users ( id INTEGER PRIMARY KEY, email TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL ); CREATE TABLE orders ( id INTEGER PRIMARY KEY, user_id INTEGER REFERENCES users(id), total_cents INTEGER NOT NULL, placed_at INTEGER NOT NULL ); `.trim(); return { contents: [ { uri: uri.href, text: schema, mimeType: "text/plain", }, ], }; }, );

Here, "db-schema" is the resource name, and "sqlite:///local.db" is the URI the client uses to request it. Choose a URI scheme that logically represents your data (e.g., `file://`, `https://`, or a custom scheme). Resources are pull-based; the model requests them when it deems them necessary.

4. Connecting to AI Clients (5 minutes) With your server built, the next step is to connect it to an MCP-compliant AI client. First, ensure your project is built: npm run build

Claude Desktop For Claude Desktop, you'll modify its configuration file. On macOS, this is typically located at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows, it's `%APPDATA%\Claude\claude_desktop_config.json`. Be aware that some Windows MSIX installations might use a different path, so always verify if your changes aren't taking effect. Add your server to the `mcpServers` block: { "mcpServers": { "color-tools": { "command": "node", "args": ["/absolute/path/to/my-mcp-server/build/index.js"] } } }

Crucially, use the absolute path to your `index.js` file. Relative paths are a common pitfall and often fail silently. After saving, fully restart Claude Desktop (quit from the menu bar, not just close the window). Open a new conversation, and you should see a hammer icon in the input bar, indicating that tools are available. Try typing "convert #3b82f6 to RGB" to see your tool in action.

Cursor Cursor uses a similar `mcpServers` JSON structure. Its global configuration file is at `~/.cursor/mcp.json`, or you can use a project-scoped file at `.cursor/mcp.json` within your project root. { "mcpServers": { "color-tools": {