Skip to main content
Glama

example-mcp-server-stdio

by yigitkonur

Calculator Learning Demo - STDIO Transport

🎯 Overview

This repository demonstrates a learning-edition MCP calculator server using STDIO transport. It showcases the Model Context Protocol (MCP) SDK implementation with standard tools/list and tools/call methods, communicating via stdin and stdout using JSON-RPC messages.

This transport is the most performant and secure option for local inter-process communication (IPC).

Key Characteristics

  • Transport Layer: Direct stdin/stdout pipes between parent (client) and child (server) processes.
  • State Model: Ephemeral, in-process memory. All state (e.g., calculation history) is lost when the process exits.
  • Latency: The lowest possible latency (microseconds), as it avoids all network stack overhead.
  • Security: Extremely high due to OS-level process isolation. There is no network attack surface.
  • Use Case: Ideal for high-performance, secure local tooling, such as command-line interfaces (CLIs), IDE plugins, and build-system integrations.

📊 Transport Comparison

This table compares the four primary MCP transport mechanisms demonstrated in the learning series. The implementation in this repository is highlighted.

DimensionSTDIOSSE (Legacy)Streamable HTTP (Stateful)Streamable HTTP (Stateless)
Transport LayerLocal Pipes (stdin/stdout)2 × HTTP endpoints (GET+POST)Single HTTP endpoint /mcpSingle HTTP endpoint /mcp
Bidirectional StreamYes (full duplex)⚠️ Server→Client only✅ Yes (server push + client stream)✅ Yes (within each request)
State ManagementEphemeral (Process Memory)Ephemeral (Session Memory)Persistent (Session State)❌ None (Stateless)
ResumabilityNone❌ None✅ Yes (Last-Event-Id)❌ None (by design)
Scalability⚠️ Single Process✅ Multi-Client✅ Horizontal (Sticky Sessions)♾️ Infinite (Serverless)
Security🔒 Process Isolation🌐 Network Exposed🌐 Network Exposed🌐 Network Exposed
Ideal Use CaseCLI Tools, IDE PluginsLegacy Web AppsEnterprise APIs, WorkflowsServerless, Edge Functions

📐 Architecture and Flow

The STDIO transport architecture is based on a parent-child process model. A client application spawns the MCP server as a child process and communicates with it by writing to the child's stdin and reading from its stdout.

MCP SDK Implementation

This repository contains a single, production-ready MCP server implementation:

  • dist/server.js - Built with the official @modelcontextprotocol/sdk
  • Uses standard MCP methods: tools/list, tools/call, resources/list, prompts/list
  • High-level abstractions with server.registerTool() and server.registerResource()
  • Compatible with all MCP clients and registries (including Smithery)

✨ Feature Compliance

This server implements the complete MCP Latest Standard feature set for the learning edition.

NameStatusImplementation
calculateCore ✅Basic arithmetic with optional streaming progress.
batch_calculateExtended ✅Processes multiple calculations in a single request.
advanced_calculateExtended ✅Factorial, logarithm, and combinatorics operations.
demo_progressExtended ✅Demonstrates progress notifications over the stdout stream.
explain-calculationCore ✅Returns a Markdown explanation of a calculation.
generate-problemsCore ✅Returns Markdown-formatted practice problems.
calculator-tutorCore ✅Returns Markdown-formatted tutoring content.
solve_math_problemExtended ✅Solves a math problem, may elicit input.
explain_formulaExtended ✅Provides an interactive formula explanation.
calculator_assistantExtended ✅Offers interactive calculator assistance.
calculator://constantsCore ✅Resource for mathematical constants (π, e, φ, etc.).
calculator://history/{id}Extended ✅Resource for the last 50 calculation results stored in memory.
calculator://statsExtended ✅Resource for server uptime and request statistics.
formulas://libraryExtended ✅Resource for a collection of mathematical formulas.

🚀 Getting Started

Prerequisites

  • Node.js (v18.x or higher)
  • npm or yarn

Installation

# Clone the repository git clone https://github.com/modelcontextprotocol/mcp-server-examples.git cd mcp-server-examples/stdio # Install dependencies npm install # Build the project npm run build

Running the Server

The server is designed to be spawned by a client. You can run it directly to send it commands interactively.

# Run the MCP server npm start # Run directly with Node.js node dist/server.js --stdio # Run in development mode npm run dev

Testing with MCP Inspector

Interact with the SDK-based server using the official MCP Inspector CLI. This command spawns the server and pipes its I/O to the inspector.

npx @modelcontextprotocol/inspector --cli "node dist/server.js --stdio"

📋 API Usage Examples

All requests use standard MCP protocol with JSON-RPC messages.

Standard MCP Protocol

The server implements the standard MCP SDK protocol:

# List available tools → {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}} # Call a tool → {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculate","arguments":{"a":7,"b":6,"op":"multiply"}}} # Response {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"7 × 6 = 42"}]}}

Progress Demonstration

Progress notifications are sent as standard JSON-RPC notifications (no id field) over stdout.

# Request → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"demo_progress","arguments":{}}} # Response Stream {"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":20,"total":100}} {"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":40,"total":100}} {"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":60,"total":100}} {"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":80,"total":100}} {"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":100,"total":100}} {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Progress demonstration completed"}]}}

🧠 State Management Model

Principle: State is ephemeral and strictly scoped to the lifetime of the server process.

  • Mechanism: All state is held in standard JavaScript variables and Map objects within the Node.js process.
  • Stored Data:
    • Calculation History: A Map stores the last 50 calculation results as a ring buffer.
    • Server Statistics: Variables track the process start time and total request count.
    • In-flight Requests: The MCP SDK maintains a Map to track concurrent requests and route responses correctly.
  • Lifecycle: When the process exits for any reason, all in-memory state is irrevocably lost. Each new process starts with a clean slate. This is a fundamental and intentional design choice for this transport.

🛡️ Security Model

The STDIO transport provides the most secure environment of all MCP transports by leveraging operating system primitives.

  • Process Isolation: The server runs in a separate memory space from the client, preventing any direct memory access or interference. The OS enforces this boundary.
  • No Network Exposure: Communication is entirely via local IPC pipes. There are no open ports, making network-based attacks (e.g., CSRF, MitM, remote exploits) impossible.
  • Input Validation: All incoming request parameters are rigorously validated by Zod schemas (defined in src/types.ts) to ensure type safety and prevent injection-style attacks.
  • Resource Limiting: The server enforces hard limits on batch sizes (maxBatchSize: 100) and history storage (maxHistorySize: 50) to prevent resource exhaustion attacks.
  • Exit Code Signaling: The server uses standard Unix exit codes to signal its termination status to the parent process (e.g., 0 for success, 65 for data errors, 70 for software errors), allowing the client to react appropriately.

🧪 Testing

This project includes a test suite that spawns the server as a child process to validate its I/O behavior.

# Run all tests defined in jest.config.js npm test # Run tests and generate a code coverage report npm run test:coverage # Run tests in watch mode for interactive development npm run test:watch

📚 Official Resources

Related MCP Servers

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yigitkonur/example-mcp-server-stdio'

If you have feedback or need assistance with the MCP directory API, please join our Discord server