Install @modelcontextprotocol/sdk and zod.
MCP / TypeScript
MCP server in TypeScript.
The MCP TypeScript SDK is small, opinionated, and works the same in Node 20+ and Bun. This is the minimum viable server, the production-quality patterns to add on top, and how to ship it via npm so any MCP client can install it.
Unlimited previews. No credit card required.
01Details
Minimum viable server (~30 lines)
Create an McpServer({ name, version }).
Register one tool with server.tool(name, description, inputSchema, handler).
Connect to StdioServerTransport. The whole thing fits in 30 lines.
02Details
package.json shape for npm publish
type: "module" — ESM by default.
bin: { "your-mcp": "./dist/index.js" } so npx -y your-mcp works.
files: ["dist", "README.md"] allowlist (not .npmignore — explicit beats implicit).
engines: { node: ">=20" } — the SDK uses native fetch and AbortController.
Pin @modelcontextprotocol/sdk to a known-good range. Early-version SDKs sometimes ship breaking minors.
03Details
Production patterns to add
Bearer auth from env: read process.env.YOUR_API_KEY and forward in every downstream call.
Sanitise errors before returning to the agent — full HTTP error bodies leak internal target IDs and request URLs.
Wrap async handlers in a try/catch and return { isError: true, content: [{ type: 'text', text: ... }] } so the agent sees a typed failure.
For image/file returns, encode to base64 and return { type: 'image', data, mimeType } — text-only handlers can't return binary.
04Details
Streamable HTTP transport (optional)
Default to stdio. Switch to Streamable HTTP when your MCP client prefers a remote URL (Cursor, Antigravity, Codex remote skills).
Use StreamableHTTPServerTransport from @modelcontextprotocol/sdk/server/streamableHttp.js.
Mount inside a normal Node http.createServer — the transport handles MCP-spec framing.
Bind to 127.0.0.1 for local; behind a reverse proxy with auth for production. Anyone who can reach the port can call your tools.
05Details
From OpenAPI to MCP — the auto path (preview)
TypeScript and Python SDKs ship today. TypeScript MCP-server emission is in preview alongside: one tool per operation, zod schemas from components/schemas, stdio transport, bin entry, README.
Preview output is an npm-shaped package under your scope. npx -y @your-co/mcp will work for any MCP client; Streamable HTTP (--port N) is on the near-term roadmap.
Same Sourced workflow that emits the TypeScript SDK, Python SDK, docs preview, and compatibility report — MCP joins the same pipeline as it lands.