0x80Lesson 9 of 16

Ship an MCP server with the TypeScript SDK

Turn a useful tool into a real MCP server with the official SDK, stdio, and a safe path to remote hosting.

18 min 4-question quiz

By the end of this lesson you can

Register a typed tool with the official TypeScript SDK
Choose stdio or Streamable HTTP for the deployment you need
Keep protocol output, logs, and secrets in the right places

The hand-built server in the capstone helps you understand the wire format. For an application you intend to use, start with the official SDK: it handles protocol framing, capability registration, and transport details so your code can focus on the job the server performs.

This example uses the current TypeScript SDK v2 package layout. Pin a compatible SDK version in your project and follow its migration guide if you are working from an older v1 tutorial; package names and protocol revisions can change.

Install the SDK and a TypeScript runner

npm install @modelcontextprotocol/server zod
npm install --save-dev typescript tsx @types/node
npx tsx src/index.ts

src/index.ts — a local server with one read-only tool

1import { McpServer } from '@modelcontextprotocol/server';
2import { serveStdio } from '@modelcontextprotocol/server/stdio';
3import * as z from 'zod/v4';
4
5const books = [
6  { title: 'The Left Hand of Darkness', author: 'Ursula K. Le Guin' },
7  { title: 'Kindred', author: 'Octavia E. Butler' },
8  { title: 'The Dispossessed', author: 'Ursula K. Le Guin' },
9];
10
11function searchBooks(query: string, options: { limit: number }) {
12  const normalizedQuery = query.toLocaleLowerCase();
13  return books
14    .filter(({ title, author }) =>
15      [title, author].join(' ').toLocaleLowerCase().includes(normalizedQuery),
16    )
17    .slice(0, options.limit);
18}
19
20function createServer() {
21  const server = new McpServer({ name: 'reading-list', version: '1.0.0' });
22
23  server.registerTool(
24    'find_book',
25    {
26      description: 'Find books by title or author. Read-only; returns at most 10 matches.',
27      inputSchema: z.object({ query: z.string().trim().min(1).max(120) }),
28    },
29    async ({ query }) => {
30      const matches = await searchBooks(query, { limit: 10 });
31      return {
32        content: [{ type: 'text', text: JSON.stringify(matches) }],
33      };
34    },
35  );
36
37  return server;
38}
39
40const handle = serveStdio(createServer);
41console.error('reading-list MCP server ready');

Pick the transport from the connection shape

Try it

Local process or remote endpoint?

Sort each deployment into the transport that fits it. The host owns the connection; MCP capabilities stay the same.

0 of 4 sortedScore 0/0

“An IDE launches your server on the developer laptop”
“A hosted service is shared by a team over a network”
“A desktop host starts a local database helper on demand”
“A server needs to authenticate network clients”

For remote deployment, use Streamable HTTP and configure authentication at the HTTP boundary. Validate bearer tokens, enforce audience and scope, apply per-user authorization inside handlers, and keep credentials out of tool arguments and logs. Do not treat CORS as authentication.

To connect the local process, add an entry to your host configuration. For VS Code, create .vscode/mcp.json in the project root:

{ "servers": { "reading-list": { "type": "stdio", "command": "npx", "args": ["tsx", "src/index.ts"] } } }

A production checklist:

Give each tool a narrow name, a plain description, and a strict input schema.
Validate authorization and every argument before accessing data or performing a side effect.
Require explicit human confirmation for consequential actions; describe the effect before approval.
Bound query size, result count, timeouts, and upstream calls.
Return useful errors without exposing tokens, stack traces, or private records.
Test with the MCP Inspector and at least one real host; record SDK, host, and protocol versions.
Review the exact server source and behavior before enabling it in a host.

Key takeaways

Use the official SDK for an application server; build the wire format by hand only to learn it.
stdio fits a host-launched local process; Streamable HTTP fits a remote endpoint.
Keep stdout clean on stdio, and treat authentication, authorization, confirmation, and limits as application responsibilities.

Lesson quiz

4 questions · pass with 3 correct · up to 50 XP

Passing this quiz completes the lesson and keeps your streak going. Questions you miss come back in review sessions later.

Questions about this lesson

Stuck? Ask. Figured something out? Share it. Explaining is one of the best ways to learn.

Loading posts…