MCP server SDK

Installation and SDK versions

npm install @modelcontextprotocol/sdk zod
# For TypeScript projects also install:
npm install --save-dev typescript @types/node

The SDK follows a major.minor.patch version scheme where the major version tracks the MCP protocol specification revision. As of 2026, the stable release series is 1.x. Pin to a minor version in production ("@modelcontextprotocol/sdk": "^1.x.0") and review the changelog before upgrading — protocol spec changes may alter the initialize response shape expected by clients. If you run protocol compliance tests, a failing compliance test after an SDK upgrade means the new protocol version changed a field your clients depend on.

The SDK is ESM-only. Your project needs "type": "module" in package.json. See MCP server TypeScript setup for the full tsconfig and build configuration.

Transport selection

Transport is the first architectural decision. The SDK ships two production-ready transports:

Choose StreamableHTTPServerTransport for any server that runs independently of the client process. This includes everything deployed to Fly.io, Railway, Docker, Kubernetes, or a plain VPS. It is also the only transport compatible with uptime monitoring — a monitoring probe cannot connect to a stdio server because there is no network address to probe. AliveMCP and every external health-check tool require HTTP transport.

Choose StdioServerTransport only for developer tools packaged as CLI executables that a client (like Claude Desktop) launches as a child process. Stdio servers run locally, cannot be monitored externally, and die when the client process closes. They have no persistent URL, no TLS, and no way to serve multiple concurrent clients.

Minimal HTTP MCP server

// src/index.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { z } from 'zod';
import express from 'express';

const server = new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

server.tool(
  'get_status',
  'Returns the current status of a service by name',
  { service: z.string().describe('Name of the service to check') },
  async (args) => {
    const status = await checkService(args.service);
    return { content: [{ type: 'text', text: JSON.stringify(status) }] };
  }
);

const app = express();
app.use(express.json());

app.post('/mcp', async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdHeader: 'mcp-session-id',
  });
  await server.connect(transport);
  await transport.handleRequest(req, res);
});

const PORT = parseInt(process.env.PORT ?? '3001', 10);
app.listen(PORT, () => console.log(`MCP server listening on :${PORT}`));

Each POST to /mcp creates a new transport instance for that request. The sessionIdHeader option tells the transport to read and write a session ID from the mcp-session-id HTTP header — clients use this to correlate subsequent requests to the same session. The first request in a session carries the initialize message; subsequent requests carry tools/list and tools/call messages. The session ends when the client disconnects or the connection times out.

Registering tools, resources, and prompts

The SDK exposes three registration methods on McpServer:

// Tool — executable function the AI agent calls
server.tool(
  'search_docs',
  'Search the documentation for a query and return matching sections',
  {
    query: z.string().min(1).describe('The search query'),
    limit: z.number().int().min(1).max(20).default(5),
  },
  async (args) => {
    const results = await searchDocs(args.query, args.limit);
    return { content: [{ type: 'text', text: JSON.stringify(results) }] };
  }
);

// Resource — data the AI agent can read (URL-addressed)
server.resource(
  'config://current',
  'Current server configuration',
  async (uri) => ({
    contents: [{ uri: uri.href, text: JSON.stringify(getConfig()), mimeType: 'application/json' }],
  })
);

// Prompt — reusable message template
server.prompt(
  'summarize',
  'Summarize a document',
  { document: z.string().describe('The document text to summarize') },
  (args) => ({
    messages: [{
      role: 'user',
      content: { type: 'text', text: `Summarize the following document:\n\n${args.document}` },
    }],
  })
);

Tools are the most commonly used primitive — they are callable functions with typed inputs. Resources expose data at a URI that clients can read without executing code. Prompts are reusable message templates that compose tool calls and user instructions. In practice, most MCP servers expose only tools. Register resources when your server has data that changes over time and clients should be able to read it directly. Register prompts only if your use case involves reusable multi-turn conversation patterns.

Session lifecycle

Every MCP session follows the same four-phase lifecycle:

1. Initialize — client sends initialize with its protocol version and capabilities. The server responds with protocolVersion, serverInfo, and its own capabilities. The SDK handles this automatically — you do not need to write an initialize handler.
2. Discovery — client calls tools/list, resources/list, and/or prompts/list to discover what the server exposes. The SDK generates these responses from your registered tools, resources, and prompts.
3. Interaction — client calls tools/call, reads resources, and uses prompts in a loop until the task is complete.
4. Termination — client disconnects or the session times out. No explicit close handshake is required.

The initialize handshake is what AliveMCP probes every 60 seconds. A successful probe means the server completed the initialize phase and responded with a valid protocol version. If your server fails the probe — because it crashed, a dependency is down, or the network path is broken — AliveMCP triggers an alert before any user session hits the broken initialize step. See MCP server health check for the exact probe logic.

Stdio server for local tools

// src/index.ts — stdio variant for local CLI tools
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: 'local-tool', version: '1.0.0' });

server.tool(
  'read_file',
  'Read a file from the local filesystem',
  { path: z.string().describe('Absolute path to the file') },
  async (args) => {
    const { readFile } = await import('node:fs/promises');
    const content = await readFile(args.path, 'utf-8');
    return { content: [{ type: 'text', text: content }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);
// The server stays alive until stdin closes

For stdio servers, the transport reads JSON-RPC messages from stdin and writes responses to stdout. All logging must go to stderr — writing anything other than valid JSON-RPC to stdout corrupts the protocol stream. Use console.error() instead of console.log() for debug output. Stdio servers cannot be externally monitored — if you need uptime visibility, use HTTP transport instead.

Related questions

Further reading

• MCP server TypeScript — type-safe tool handlers with Zod and the official SDK
• MCP server authentication — securing access with API keys and OAuth 2.0
• MCP server versioning — protocol negotiation and backward-compatible schema changes
• MCP server testing — protocol compliance and schema snapshot tests
• MCP server deployment — containerized HTTP transport on Fly.io, Railway, and Docker
• MCP server health check — what the initialize probe verifies
• AliveMCP — uptime monitoring for every MCP endpoint