MCP STDIO Server with Error Response

A minimal Model Context Protocol (MCP) server implementation in Rust designed for testing error handling in MCP clients. This server intentionally returns error responses to help developers verify their client's error handling capabilities.

Overview

This test server implements the MCP protocol over STDIO and provides two operational modes:

1. Error Mode (default): Returns JSON-RPC error responses for all methods except notifications
2. Success Mode (--init-ok flag): Successfully handles the initialize method, then returns errors for all other methods

Features

• ✅ Implements MCP protocol version 2024-11-05
• ✅ STDIO-based communication (JSON-RPC 2.0)
• ✅ Configurable initialization behavior via command-line flag
• ✅ Proper handling of JSON-RPC notifications (no response)
• ✅ Intentional error responses for testing client error handling

Installation

Prerequisites

• Rust 1.70+ (edition 2024)
• Cargo

Build from Source

cargo build --release

The compiled binary will be available at target/release/mcp-stdio-server-with-error-response.

Usage

Running the Server

Error Mode (default):

cargo run

Success Mode (initialize succeeds):

cargo run -- --init-ok

Testing with the Provided Script

A test script is included to demonstrate the server's behavior:

chmod +x test.sh
./test.sh

The test script sends:

1. An initialize request
2. A notifications/initialized notification
3. A tools/list request

Protocol Behavior

Initialize Method

With --init-ok flag:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "Error-Test-Server",
      "version": "1.0"
    }
  }
}

Without --init-ok flag:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Intentional failure on method: 'initialize'"
  }
}

Other Methods

All other methods (except notifications) receive error responses:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32603,
    "message": "Intentional failure on method: 'tools/list'"
  }
}

Notifications

Notifications (requests without an id field or with method notifications/initialized) are properly ignored per JSON-RPC 2.0 specification.

Use Cases

This server is useful for:

• Testing MCP client error handling: Verify your client properly handles server errors
• Development and debugging: Test client behavior when servers fail
• Integration testing: Validate error recovery mechanisms
• Protocol compliance: Ensure clients follow JSON-RPC 2.0 error handling

Error Code

The server returns error code -32603 (Internal error) for all intentional failures, which is a standard JSON-RPC 2.0 error code indicating an internal server error.

Dependencies

• tokio - Async runtime (with full features)
• serde_json - JSON serialization/deserialization