How to Build an MCP Server: A Practical TypeScript Guide

Prepare the contract before installing the SDK

Start from the consumer and data boundary. A server that exposes every internal function is harder for clients to select correctly, harder to authorize, and much harder to operate.

• One client job and a capability inventory: Write the user requests the server should handle, the requests it must refuse, and whether each capability belongs in a model-controlled tool, application-controlled resource, or user-controlled prompt.
• A transport decision: Use stdio when a local client launches the server process. Use Streamable HTTP for remote servers. Treat the older HTTP+SSE transport as a compatibility requirement, not the default for a new server.
• Node.js, TypeScript, and current SDK versions: This walkthrough uses the official TypeScript SDK v1.x server API with @modelcontextprotocol/sdk 1.29.0 and Zod, the registry version checked July 19, 2026. Recheck the official branch and release notes before a later install.
• Data ownership and failure budgets: Name each upstream API, timeout, rate limit, cache rule, retry policy, sensitive field, retention period, and operator. Decide which failures are safe for a model to retry and which require a human decision.

Credentials and access

Choose the smallest transport and state model that fits

MCP separates server capabilities from transport. Build the same capability layer behind a transport adapter so local development does not lock the production design to a subprocess or HTTP implementation.

Recommended:Start with stdio for the first local contract test. For a remote server, prefer stateless Streamable HTTP unless a named capability needs sessions or SSE notifications. Keep legacy HTTP+SSE only when an actual client still requires it.

Build, test, deploy, and operate an MCP server

Design a narrow protocol contract, implement typed capabilities, test them with Inspector and fixtures, then deploy and monitor a secure Streamable HTTP endpoint.

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: 'forecast-server', version: '1.0.0' })

server.registerTool(
  'get_forecast',
  {
    title: 'Get forecast',
    description: 'Return the latest read-only forecast for one supported city.',
    inputSchema: { city: z.string().trim().min(2).max(80) },
    outputSchema: {
      forecast: z.object({ city: z.string(), summary: z.string(), observedAt: z.string() }),
    },
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
  },
  async ({ city }) => {
    const forecast = await forecastStore.get(city)
    if (!forecast) {
      return { content: [{ type: 'text', text: 'No supported city matched the input.' }], isError: true }
    }
    const output = { forecast }
    return {
      content: [{ type: 'text', text: JSON.stringify(output) }],
      structuredContent: output,
    }
  },
)

await server.connect(new StdioServerTransport())

import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

server.registerResource(
  'forecast-notes',
  new ResourceTemplate('forecast://{city}/notes', { list: undefined }),
  { title: 'Forecast notes', mimeType: 'text/markdown' },
  async (uri, { city }) => ({
    contents: [{ uri: uri.href, mimeType: 'text/markdown', text: await notesStore.read(city) }],
  }),
)

server.registerPrompt(
  'plan-outdoor-work',
  {
    title: 'Plan outdoor work',
    description: 'Draft a weather-aware work plan after the user selects this prompt.',
    argsSchema: { city: z.string(), task: z.string() },
  },
  ({ city, task }) => ({
    messages: [{ role: 'user', content: { type: 'text', text: 'Plan ' + task + ' in ' + city + '.' } }],
  }),
)

The minimum MCP server test matrix

Test from a real MCP client boundary. Calling the handler directly misses initialization, capability negotiation, serialization, transport headers, cancellation, and error envelopes.

Common failures and the evidence that separates them

Start with the raw protocol exchange and transport logs. A client saying the server is unavailable can describe a corrupted stdio stream, a negotiation mismatch, a rejected HTTP header, or a crashed handler.

Deploy and operate the server as a protocol product

Deploy

Pin SDK and runtime versions, build an immutable artifact, run as a non-root user, expose only HTTPS /mcp and a separate shallow health endpoint, and keep admin or debug routes private.

Use readiness only after dependencies needed for safe requests are available. Drain active requests on shutdown. If sessions are stateful, preserve or explicitly terminate them before replacing an instance.

Monitor

Track initialize success and negotiated versions, method latency, schema errors, isError categories, authorization outcomes, rate limits, timeouts, cancellations, session count, event-replay lag, and upstream health.

Run a scheduled production smoke with a harmless read capability and a dedicated least-privilege identity. Do not use a write tool as the heartbeat.

Recover

Keep the previous artifact and capability schema available for rollback. If a schema change breaks clients, restore the old contract first, then introduce the replacement under a versioned capability or coordinated release.

Revoke exposed credentials, rotate the separate upstream secret, invalidate affected sessions, and audit by correlation ID. Never relax audience or scope validation to make a failing client connect.

Security controls that belong in the first version

MCP makes capabilities discoverable; it does not make them trustworthy. Treat every client field, resource URI, prompt argument, upstream response, and returned link as untrusted at the server boundary.

• Validate tool inputs and outputs against explicit schemas, reject unknown fields when the contract does not need them, and bound strings, arrays, payload sizes, and execution time.
• Authorize every tool and resource independently. Discovery visibility is not permission to execute or read.
• For HTTP, validate Origin and Host, use HTTPS, bind local servers to loopback, enforce rate limits, and protect against DNS rebinding and cross-client token misuse.
• Validate token audience for the canonical MCP resource and never pass the inbound token through to an upstream service.
• Keep secrets out of source control, URLs, stdout, tool content, structuredContent, resources, prompts, traces, screenshots, and generated error text.
• Sanitize upstream content, defend against prompt injection in resources and templates, and do not let model-provided paths, URLs, or shell fragments reach privileged operations unchecked.
• Require confirmation and idempotency for writes, isolate destructive tools, retain a minimal audit reference, and make rollback or compensation explicit.

MCP server questions