MCP Echo Server

1.0.0 verified Sat Apr 25 auth: no javascript

A minimal Model Context Protocol (MCP) server template that provides an echo tool for testing and as a starting point for building custom MCP servers. Version 1.0.0 is the initial release. It uses the @modelcontextprotocol/sdk and is intended for developers creating MCP-compliant tools. Key differentiators: it is a barebones template with minimal dependencies, TypeScript support, and ready for npm publishing, unlike more complex starter kits.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /.../@modelcontextprotocol/sdk/... from ... not supported. ↓

cause Using CommonJS require() with ESM-only package.

fix

Switch to ES modules: add 'type': 'module' to your package.json or use dynamic import().

error Cannot find module '@modelcontextprotocol/sdk' or its corresponding type declarations. ↓

cause Missing @modelcontextprotocol/sdk in node_modules; not installed.

fix

Run: npm install @modelcontextprotocol/sdk

error Error: No matching export for import "@modelcontextprotocol/sdk". ↓

cause Using a bare import '@modelcontextprotocol/sdk' without subpath.

fix

Use a specific subpath like '@modelcontextprotocol/sdk/server/index.js'.

Warnings

breaking ESM-only: The @modelcontextprotocol/sdk is ESM-only. Using require() will fail with ERR_REQUIRE_ESM. ↓

fix Set 'type': 'module' in package.json or use dynamic import().

gotcha Import paths are not from the package root; subpath exports are used. ↓

fix Use specific subpath imports: '@modelcontextprotocol/sdk/server/index.js', etc.

gotcha The 'server.tool' method is async but callback can be sync; omitting async may cause unexpected behavior. ↓

fix Always define tool handlers as async functions.

deprecated Some older versions of the SDK used 'server.setRequestHandler' directly; now tools are registered via 'server.tool'. ↓

fix Use server.tool() method instead of manual handler registration.

Install

npm install mcp-echo-server

yarn add mcp-echo-server

pnpm add mcp-echo-server

Imports

Server

wrong

const { Server } = require('@modelcontextprotocol/sdk/server/index.js')

correct

import { Server } from '@modelcontextprotocol/sdk/server/index.js'

ESM-only package; requires Node >=18 and 'type': 'module' in package.json.

StdioServerTransport

wrong

import { StdioServerTransport } from '@modelcontextprotocol/sdk'

correct

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

Exported from a specific subpath, not the main entry.

z
```
import { z } from 'zod'
```
Used for parameter schema validation; zod is a peer dependency of @modelcontextprotocol/sdk.
CallToolResultSchema
```
import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js'
```
Type for tool response; also available from the server module.

Quickstart

Demonstrates creating a minimal MCP server with a single 'echo' tool using the @modelcontextprotocol/sdk.

// src/index.ts (ESM)
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new Server(
  { name: 'mcp-echo-server', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.tool(
  'echo',
  'Echoes back the message',
  { message: z.string().describe('The message to echo') },
  async ({ message }) => ({
    content: [{ type: 'text', text: message }]
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);