How to Build an MCP Server in TypeScript (2026 Step-by-Step Guide)

# 1. Create the project folder
mkdir notes-mcp && cd notes-mcp
npm init -y

# 2. Install the MCP server SDK (v2) + Zod for input validation
npm install @modelcontextprotocol/server zod

# 3. Dev tools: TypeScript, tsx (run .ts directly) and Node types
npm install -D typescript tsx @types/node

# 4. Create the folders we'll use
mkdir -p src/tools

# Overwrite package.json with ES modules + handy scripts
cat > package.json <<'EOF'
{
  "name": "notes-mcp",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "inspect": "npx @modelcontextprotocol/inspector npx tsx src/index.ts"
  }
}
EOF

# npm init cleared the dependency list, so re-add it
npm install @modelcontextprotocol/server zod
npm install -D typescript tsx @types/node

cat > tsconfig.json <<'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src"]
}
EOF

$ tree -I node_modules
notes-mcp/
├── src/
│   ├── index.ts          # stdio entry point
│   ├── server.ts         # builds the McpServer and registers everything
│   ├── store.ts          # in-memory notes store
│   ├── resources.ts      # resources (Example 4)
│   ├── prompts.ts        # prompts (Example 5)
│   ├── http.ts           # remote HTTP entry point
│   ├── test-client.ts    # automated smoke test (Example 6)
│   └── tools/
│       ├── notes.ts      # add / list / search (Example 1)
│       ├── admin.ts      # delete / get with errors (Example 2)
│       └── github.ts     # GitHub API tool (Example 3)
├── package.json
└── tsconfig.json

# ── src/store.ts: a tiny in-memory store (swap for a database later) ──
cat > src/store.ts <<'EOF'
export type Note = { id: number; title: string; body: string; createdAt: string };

export const notes = new Map<number, Note>();
let nextId = 1;

export function addNote(title: string, body: string): Note {
  const note = { id: nextId++, title, body, createdAt: new Date().toISOString() };
  notes.set(note.id, note);
  return note;
}
EOF

# ── src/tools/notes.ts: add / list / search tools ──
cat > src/tools/notes.ts <<'EOF'
import type { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';
import { notes, addNote } from '../store.js';

export function registerNoteTools(server: McpServer) {
  // ➊ Add a note
  server.registerTool(
    'add-note',
    {
      description: 'Save a new note with a title and body. Returns the new note id.',
      inputSchema: z.object({
        title: z.string().min(1).describe('Short title, e.g. "Sprint goals"'),
        body: z.string().describe('The note content')
      })
    },
    async ({ title, body }) => {
      const note = addNote(title, body);
      return { content: [{ type: 'text', text: `Saved note #${note.id}: ${title}` }] };
    }
  );

  // ➋ List all notes
  server.registerTool(
    'list-notes',
    {
      description: 'List all saved notes with their ids and titles',
      inputSchema: z.object({})
    },
    async () => {
      const text = notes.size
        ? [...notes.values()].map(n => `#${n.id} ${n.title}`).join('\n')
        : 'No notes yet.';
      return { content: [{ type: 'text', text }] };
    }
  );

  // ➌ Search notes by keyword
  server.registerTool(
    'search-notes',
    {
      description: 'Search notes by keyword in the title or body',
      inputSchema: z.object({ query: z.string().min(1) })
    },
    async ({ query }) => {
      const q = query.toLowerCase();
      const found = [...notes.values()].filter(
        n => n.title.toLowerCase().includes(q) || n.body.toLowerCase().includes(q)
      );
      const text = found.length
        ? found.map(n => `#${n.id} ${n.title}: ${n.body}`).join('\n')
        : `No notes match "${query}".`;
      return { content: [{ type: 'text', text }] };
    }
  );
}
EOF

# ── src/server.ts: build the server (we'll add more modules later) ──
cat > src/server.ts <<'EOF'
import { McpServer } from '@modelcontextprotocol/server';
import { registerNoteTools } from './tools/notes.js';

export function createServer() {
  const server = new McpServer({ name: 'notes', version: '1.0.0' });
  registerNoteTools(server);
  return server;
}
EOF

cat > src/index.ts <<'EOF'
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import { createServer } from './server.js';

serveStdio(() => createServer());
EOF

# Quick check: open the Inspector and try the 3 tools
npm run inspect

cat > src/tools/admin.ts <<'EOF'
import type { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';
import { notes } from '../store.js';

export function registerAdminTools(server: McpServer) {
  // ➍ Delete a note – Option A: return isError with a helpful message
  server.registerTool(
    'delete-note',
    {
      description: 'Delete a note by its numeric id',
      inputSchema: z.object({ id: z.number().int().positive() })
    },
    async ({ id }) => {
      if (!notes.has(id)) {
        return {
          content: [{
            type: 'text',
            text: `No note with id ${id}. Known ids: ${[...notes.keys()].join(', ') || 'none'}`
          }],
          isError: true
        };
      }
      notes.delete(id);
      return { content: [{ type: 'text', text: `Deleted note #${id}` }] };
    }
  );

  // ➎ Get one note – Option B: just throw; the SDK turns it into an isError result
  server.registerTool(
    'get-note',
    {
      description: 'Get the full content of one note by id',
      inputSchema: z.object({ id: z.number().int().positive() })
    },
    async ({ id }) => {
      const note = notes.get(id);
      if (!note) throw new Error(`Note #${id} not found`);
      return { content: [{ type: 'text', text: `${note.title}\n\n${note.body}` }] };
    }
  );
}
EOF

cat > src/tools/github.ts <<'EOF'
import type { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';

export function registerGithubTools(server: McpServer) {
  // ➏ Get GitHub repository info
  server.registerTool(
    'get-github-repo',
    {
      description: 'Get stars, forks, open issues and language for a public GitHub repo',
      inputSchema: z.object({
        owner: z.string().describe('Repo owner, e.g. "facebook"'),
        repo: z.string().describe('Repo name, e.g. "react"')
      })
    },
    async ({ owner, repo }) => {
      const headers: Record<string, string> = {
        'Accept': 'application/vnd.github+json',
        'User-Agent': 'notes-mcp'
      };
      // Optional: higher rate limits with a token from your environment
      if (process.env.GITHUB_TOKEN) {
        headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
      }

      const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, { headers });
      if (res.status === 404) throw new Error(`Repository ${owner}/${repo} not found`);
      if (!res.ok) throw new Error(`GitHub API error: ${res.status} ${res.statusText}`);

      const data = await res.json();
      const summary = [
        `📦 ${data.full_name}`,
        `${data.description ?? 'No description'}`,
        `⭐ Stars: ${data.stargazers_count}`,
        `🍴 Forks: ${data.forks_count}`,
        `🐞 Open issues: ${data.open_issues_count}`,
        `💻 Language: ${data.language ?? 'n/a'}`,
        `🔗 ${data.html_url}`
      ].join('\n');

      return { content: [{ type: 'text', text: summary }] };
    }
  );
}
EOF

# Optional: export a token for higher GitHub rate limits
export GITHUB_TOKEN=ghp_your_token_here

cat > src/resources.ts <<'EOF'
import { McpServer, ResourceTemplate } from '@modelcontextprotocol/server';
import { notes } from './store.js';

export function registerResources(server: McpServer) {
  // Static resource: app configuration
  server.registerResource(
    'config',
    'config://app',
    {
      title: 'Application Config',
      description: 'Current notes app settings',
      mimeType: 'text/plain'
    },
    async uri => ({
      contents: [{ uri: uri.href, text: 'max_notes=500\ndefault_tag=general' }]
    })
  );

  // Dynamic resource: any single note by id, e.g. notes://3
  server.registerResource(
    'note',
    new ResourceTemplate('notes://{id}', {
      // list lets clients discover every available note
      list: async () => ({
        resources: [...notes.values()].map(n => ({
          uri: `notes://${n.id}`,
          name: n.title
        }))
      })
    }),
    {
      description: 'A single note as JSON',
      mimeType: 'application/json'
    },
    async (uri, { id }) => {
      const note = notes.get(Number(id));
      if (!note) throw new Error(`Note ${id} not found`);
      return {
        contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(note, null, 2) }]
      };
    }
  );
}
EOF

cat > src/prompts.ts <<'EOF'
import type { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';
import { notes } from './store.js';

export function registerPrompts(server: McpServer) {
  // Prompt 1: code review
  server.registerPrompt(
    'review-code',
    {
      title: 'Code Review',
      description: 'Review code for bugs, performance and best practices',
      argsSchema: z.object({
        code: z.string().describe('The code to review'),
        language: z.string().optional().describe('e.g. TypeScript, Python')
      })
    },
    ({ code, language }) => ({
      messages: [{
        role: 'user' as const,
        content: {
          type: 'text' as const,
          text: `You are a senior ${language ?? ''} developer. Review this code. ` +
                `List bugs, performance issues and improvements, with fixed code:\n\n${code}`
        }
      }]
    })
  );

  // Prompt 2: summarise all notes
  server.registerPrompt(
    'summarize-notes',
    {
      title: 'Summarize my notes',
      description: 'Create a short summary and action items from all saved notes',
      argsSchema: z.object({})
    },
    () => ({
      messages: [{
        role: 'user' as const,
        content: {
          type: 'text' as const,
          text: 'Summarize these notes in 5 bullet points, then list action items:\n\n' +
                [...notes.values()].map(n => `- ${n.title}: ${n.body}`).join('\n')
        }
      }]
    })
  );
}
EOF

# Wire every module into the server
cat > src/server.ts <<'EOF'
import { McpServer } from '@modelcontextprotocol/server';
import { registerNoteTools } from './tools/notes.js';
import { registerAdminTools } from './tools/admin.js';
import { registerGithubTools } from './tools/github.js';
import { registerResources } from './resources.js';
import { registerDocsResource } from './docs-resource.js';
import { registerPrompts } from './prompts.js';

export function createServer() {
  const server = new McpServer({ name: 'notes', version: '1.0.0' });

  registerNoteTools(server);    // Example 1
  registerAdminTools(server);   // Example 2
  registerGithubTools(server);  // Example 3
  registerResources(server);    // Example 4
  registerDocsResource(server); // Example 4 (bonus)
  registerPrompts(server);      // Example 5

  return server;
}
EOF

# Type-check everything
npx tsc --noEmit && echo '✅ All good'

npm run inspect
# same as:
npx @modelcontextprotocol/inspector npx tsx src/index.ts

npm install @modelcontextprotocol/client

cat > src/test-client.ts <<'EOF'
import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

const client = new Client({ name: 'smoke-test', version: '1.0.0' });
const transport = new StdioClientTransport({ command: 'npx', args: ['tsx', 'src/index.ts'] });

await client.connect(transport);
console.log('Connected to', client.getServerVersion());

// 1. Which tools does the server expose?
const { tools } = await client.listTools();
console.log('Tools:', tools.map(t => t.name));

// 2. Call a tool
const added = await client.callTool({
  name: 'add-note',
  arguments: { title: 'Test', body: 'Hello from the test client' }
});
console.log(added.content);

// 3. Read a resource
const { contents } = await client.readResource({ uri: 'notes://1' });
console.log(contents[0]);

await client.close();
EOF

$ npx tsx src/test-client.ts
Connected to { name: 'notes', version: '1.0.0' }
Tools: [ 'add-note', 'list-notes', 'search-notes', 'delete-note', 'get-note', 'get-github-repo' ]
[ { type: 'text', text: 'Saved note #1: Test' } ]
{ uri: 'notes://1', mimeType: 'application/json', text: '{ "id": 1, "title": "Test", ... }' }

npm install @modelcontextprotocol/express @modelcontextprotocol/node express

cat > src/http.ts <<'EOF'
import { createMcpExpressApp } from '@modelcontextprotocol/express';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createMcpHandler } from '@modelcontextprotocol/server';
import { createServer } from './server.js';

const handler = createMcpHandler(() => createServer());

const app = createMcpExpressApp(); // adds JSON parsing + DNS-rebinding protection
const node = toNodeHandler(handler);

app.all('/mcp', (req, res) => void node(req, res, req.body));

const PORT = Number(process.env.PORT ?? 3000);
app.listen(PORT, () => console.error(`MCP server on http://localhost:${PORT}/mcp`));
EOF

# Start the remote server
npx tsx src/http.ts

cat > src/http-client.ts <<'EOF'
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const client = new Client({ name: 'my-client', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp')));

const { tools } = await client.listTools();
console.log('Remote tools:', tools.map(t => t.name));
await client.close();
EOF

# In a second terminal (while src/http.ts is running)
npx tsx src/http-client.ts

npm run build   # creates dist/index.js

CONFIG="$HOME/Library/Application Support/Claude/claude_desktop_config.json"
mkdir -p "$(dirname "$CONFIG")"
[ -f "$CONFIG" ] && cp "$CONFIG" "$CONFIG.backup"   # keep a backup!

# ⚠️ This replaces the file. If you already have other servers, merge by hand.
cat > "$CONFIG" <<EOF
{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["$(pwd)/dist/index.js"],
      "env": { "GITHUB_TOKEN": "your-token-here" }
    }
  }
}
EOF

mkdir -p .vscode
cat > .vscode/mcp.json <<EOF
{
  "servers": {
    "notes": {
      "type": "stdio",
      "command": "node",
      "args": ["$(pwd)/dist/index.js"]
    }
  }
}
EOF

mkdir -p .cursor
cat > .cursor/mcp.json <<EOF
{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["$(pwd)/dist/index.js"]
    }
  }
}
EOF