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

I had Claude Desktop open. I needed it to query a local SQLite database without copy-pasting schema dumps into the chat. Thirty minutes later I had a working MCP server. Here is the exact path I took, stripped of dead ends.

TL;DR

Step	What you build	Time
Project setup	npm project, tsconfig, SDK install	5 min
First tool	Structured input, structured output	10 min
First resource	Read-only data the model can request	8 min
Connect Claude Desktop	Config file, restart, verify	5 min
Common pitfalls	Avoid the three bugs that kill every first attempt	2 min

What MCP actually is

Model Context Protocol is a standard for connecting AI models to external data and tools. The model issues requests, your server handles them, and the results come back in a format the model understands. That is the whole idea.

Before MCP, every tool integration was custom. OpenAI had function calling. Anthropic had tool use. Cursor had its own plugin format. MCP standardizes the wire protocol so you write one server and any compliant client can call it, whether that is Claude Desktop, Cursor, or a client you build yourself.

The three primitives you care about:

• Resources: read-only data the model can fetch, like files or database rows.
• Tools: functions the model can call with arguments, like running a query or sending a request.
• Prompts: reusable prompt templates the client can surface to the user.

This tutorial covers tools and resources. Prompts follow the same pattern and you will not need them for most servers.

1. Project setup

Node 18 or higher required. Check with node --version.

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

The SDK package is @modelcontextprotocol/sdk. The version on npm as of May 2026 is 1.11.x. Zod handles schema validation for tool inputs.

Update package.json with these fields:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node build/index.js"
  }
}

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

2. Implementing a tool

A tool is a function the model can call. You define its name, description, input schema, and handler. The model reads the description and schema to decide when and how to call it.

Here is a complete server with one tool that converts a hex color to RGB:

// 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);

Three things to notice:

The description string is what the model reads to decide whether to call the tool. Write it as plainly as you would write a JSDoc comment for a teammate. Vague descriptions produce missed calls or wrong inputs.

The second argument to server.tool() is the description. The third is a Zod schema object. The SDK turns this into a JSON Schema that the client sends to the model. Keep schemas tight: required fields only, no optional fields that do not change the output.

The return value must have a content array. Each item has a type and a text (or data for binary). Return JSON as a string inside a text item. The model can parse it from there.

Build and test 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. That confirms the server starts and responds to the list request.

3. Implementing a resource

Resources expose read-only data the model can pull on demand. A common use case: expose the schema of your local database so the model knows the table structure before writing a query.

Add this before the transport setup:

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",
        },
      ],
    };
  },
);

The first argument is the resource name. The second is the URI the client uses to request it. Pick a URI scheme that makes sense for your data: file, sqlite, https, or a custom scheme like myapp://.

Resources are pull-based. The model requests them when it decides it needs them. If you want data pushed into every conversation automatically, that is a different pattern (system prompt injection at the client level, not a resource).

4. Hooking it up to Claude Desktop

Build the project:

npm run build

Open your Claude Desktop config file. On macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

On Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add your server to the mcpServers block:

{
  "mcpServers": {
    "color-tools": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/build/index.js"]
    }
  }
}

Use the absolute path. Relative paths fail silently, which is the single most common first-timer mistake. Restart Claude Desktop fully (quit from the menu bar, not just close the window). Open a new conversation. You should see a hammer icon in the input bar indicating tools are available. Type "convert #3b82f6 to RGB" and watch it call the tool.

For Cursor, the config lives at ~/.cursor/mcp.json and uses the same mcpServers JSON shape:

{
  "mcpServers": {
    "color-tools": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/build/index.js"]
    }
  }
}

For a generic client or testing: the MCP Inspector from Anthropic runs tool calls through a web UI without configuring Claude Desktop.

npx @modelcontextprotocol/inspector node /absolute/path/to/build/index.js

Open the Inspector UI at port 6274 and you can fire tool calls manually and inspect the raw JSON-RPC traffic.

5. Transport choice: stdio vs HTTP

The setup above uses stdio transport. The client starts your server as a child process and communicates over stdin/stdout. This works for local tools and is the path of least resistance for Claude Desktop and Cursor.

For a remote server that two or more clients share, you need HTTP transport. The SDK ships StreamableHttpServerTransport for this. You pair it with an HTTP framework (Hono, Express, Fastify) and handle sessions. That setup adds meaningful complexity and is worth a separate article. Start with stdio unless you are building a shared service from day one.

One rule that applies to both: never write to stdout with console.log in a stdio server. The MCP protocol uses stdout for JSON-RPC frames. A stray log line corrupts the framing and the client sees a parse error with no helpful message. Use console.error() for debugging output. Everything sent to stderr is safe.

6. Common pitfalls

The three mistakes I see in every first MCP server attempt:

Schema validation gaps break calls silently. If the model sends an input that does not match your Zod schema, the SDK rejects it with a generic error. The model may retry with the same bad input. Write the schema narrowly and add .describe() calls on each field to help the model understand what values are valid.

// add field-level descriptions so the model knows what to send
{
  hex: z.string()
    .regex(/^#[0-9a-fA-F]{6}$/)
    .describe("Six-digit hex color with leading #, e.g. #ff5733"),
}

Error responses need the right shape. When your tool handler throws, return a structured error instead of letting the exception propagate:

async ({ hex }) => {
  try {
    const r = parseInt(hex.slice(1, 3), 16);
    // ... rest of handler
    return { content: [{ type: "text", text: JSON.stringify({ r, g, b }) }] };
  } catch (err) {
    return {
      content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : "unknown"}` }],
      isError: true,
    };
  }
}

The isError: true flag tells the client the call failed, which surfaces properly in Claude Desktop rather than showing as a successful response with error text inside.

Resource URIs must be stable. If a client caches a resource URI and your server changes it on restart, the cached reference points nowhere. Treat resource URIs like public API paths: change them only when you intend a breaking change and version them if needed.

The bottom line

MCP is not a new protocol that requires learning a whole ecosystem. The SDK is thin. You write a handler function, attach a schema, return a content array. The hard part is designing the right tools: narrow enough to be reliable, broad enough to be useful. A tool that does one thing with a clear input schema outperforms a general-purpose tool with six optional fields every time.

Build the color tool above. Get it running in Claude Desktop. Then replace the hex conversion with whatever data or action you actually want to expose. The scaffolding is identical regardless of what the tool does.

What would you expose through an MCP server if you had it running today?

---

GDS K S · thegdsks.com · follow on X @thegdsks

The scaffolding is 30 minutes; the tool design is the actual work.
resource" in a monospace font. Cool teal and electric blue
palette, minimal, vector-clean, no faces, no logos, no text beyond the card
labels. Subtle grid overlay on the background.