mcp-stdio

Zero-dependency MCP server for stdio transport. Just tools, nothing else.

Why

The official MCP SDK has 17 dependencies (Express, Hono, OAuth, JWT...). Most MCP servers just need stdio + tools. This package is 222 lines, zero runtime dependencies.

	@modelcontextprotocol/sdk	mcp-stdio
Dependencies	17	0
Transport	stdio, HTTP, SSE	stdio
Features	tools, resources, prompts, sampling, auth	tools
Lines	~5000+	222

Install

npm install mcp-stdio

Usage

import { createMcpServer } from 'mcp-stdio';

createMcpServer({
  name: 'my-server',
  version: '1.0.0',
  tools: {
    greet: {
      description: 'Say hello',
      parameters: {
        type: 'object',
        properties: { name: { type: 'string' } },
        required: ['name'],
      },
      handler: async ({ name }) => `Hello ${name}!`,
    },

    add: {
      description: 'Add two numbers',
      parameters: {
        type: 'object',
        properties: {
          a: { type: 'number' },
          b: { type: 'number' },
        },
        required: ['a', 'b'],
      },
      handler: async ({ a, b }) => `${Number(a) + Number(b)}`,
    },
  },
});

Configure in Claude Code

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["my-server.js"]
    }
  }
}

API

createMcpServer(options)

Starts an MCP server reading JSON-RPC from stdin, writing to stdout.

Options:

Field	Type	Required	Description
name	string	yes	Server name (shown to clients)
version	string	no	Server version (default: '0.1.0')
tools	Record<string, ToolDefinition>	yes	Tool definitions

ToolDefinition:

Field	Type	Required	Description
description	string	yes	What the tool does
parameters	JsonSchema	no	JSON Schema for input
handler	(params) => Promise<string | ToolContent[]>	yes	Implementation

Handler return types:

• string — wrapped as [{ type: 'text', text: '...' }]
• ToolContent[] — returned as-is (supports text, image, resource)

Errors in handlers are caught and returned as { isError: true, content: [{ type: 'text', text: 'Error: ...' }] } — the server never crashes.

What it implements

• JSON-RPC 2.0 over stdio (newline-delimited)
• initialize with capability negotiation
• tools/list with JSON Schema input schemas
• tools/call with structured content responses
• ping
• Proper error codes (-32700, -32600, -32601, -32603)
• Notification handling (no response for messages without id)
• Logs to stderr (stdout is protocol-only)

What it doesn't implement

• HTTP/SSE/Streamable HTTP transport
• Resources, Prompts, Sampling
• OAuth, authentication
• Schema validation (trusts the caller — your handler validates)

These are intentional omissions. If you need them, use the official SDK.

License

MIT