MCP Echo Service

A Model Context Protocol (MCP) service that provides echo tools for testing MCP protocol functionality.

Features

echo_message: Echo back a message with optional uppercase formatting
echo_with_delay: Echo back a message after a simulated delay (max 5 seconds)
echo_json: Echo back structured JSON data with analysis

Quick Start

Local Development

# Clone the repository
git clone https://github.com/NimbleBrainInc/mcp-echo.git
cd mcp-echo

# Install dependencies with uv
uv sync

# Run the server
uv run python server.py

# Or install in editable mode
uv pip install -e .
python server.py

The server will start on http://localhost:8000 with:

Health check: GET /health
MCP endpoint: POST /mcp/ (note the trailing slash)

Docker

# Build the image
docker build -t nimbletools/mcp-echo .

# Run the container
docker run -p 8000:8000 nimbletools/mcp-echo

MCP Protocol Support

This server implements the full MCP (Model Context Protocol) specification:

Transport: Streamable HTTP with Server-Sent Events (SSE)
Session Management: Proper initialization handshake required
Protocol Version: 2024-11-05
Framework: FastMCP 2.11.2
Python Version: 3.13+

Session Management

The server requires proper MCP initialization:

Initialize: Send initialize request to establish session
Initialized: Send notifications/initialized notification
Tools: Use session ID for all subsequent requests

API Usage

Complete MCP Example

# Step 1: Initialize session
INIT_RESPONSE=$(curl -s -i -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "example-client", "version": "1.0.0"}
    },
    "id": 1
  }')

# Extract session ID
SESSION_ID=$(echo "$INIT_RESPONSE" | grep -i "mcp-session-id" | cut -d' ' -f2 | tr -d '\r')

# Step 2: Send initialized notification
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

# Step 3: List available tools
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}'

# Step 4: Call echo_message tool
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call", 
    "params": {
      "name": "echo_message",
      "arguments": {"message": "Hello Echo!", "uppercase": true}
    },
    "id": 3
  }'

# Step 5: Call echo_with_delay tool  
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "echo_with_delay",
      "arguments": {"message": "Delayed Echo", "delay_seconds": 1}
    },
    "id": 4
  }'

# Step 6: Call echo_json tool
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "echo_json", 
      "arguments": {"data": {"test": "value", "number": 42}}
    },
    "id": 5
  }'

Simple Health Check

curl http://localhost:8000/health

Development

Testing

# Install with dev dependencies
uv sync --group dev

# Run tests (includes async MCP client tests)
uv run python -m pytest

# Run with coverage
uv run python -m pytest --cov=server

# Run specific test
uv run python -m pytest tests/test_server.py::test_echo_message_tool -v

Building and Deployment

# Build Docker image
docker build -t mcp-echo .

# Test the container
docker run -d --name mcp-test -p 8000:8000 mcp-echo

# Check health
curl http://localhost:8000/health

# Clean up
docker stop mcp-test && docker rm mcp-test

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

About

Part of the NimbleTools ecosystem. From the makers of NimbleBrain.

License

MIT License - see LICENSE file for details.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Provides echo tools for testing MCP protocol functionality with message echoing, delayed responses, and JSON data analysis capabilities.

Related MCP Servers

MCP Everything
s2005
-
security
A
license
-
quality
A test server implementing all features of the MCP protocol, including prompts, tools, resources, and sampling, designed for testing MCP clients rather than practical applications.
Last updated -
MIT License
Echo MCP Server
piebro
A
security
A
license
A
quality
A simple server implementing the Model Context Protocol (MCP) that echoes messages back, designed for testing MCP clients.
Last updated -
1
2
MIT License
MCP Perplexity Server
chrishayuk
A
security
A
license
A
quality
A lightweight Python-based microservice that provides simple echo functionality, receiving messages and returning them back to the client for diagnostic and testing purposes within the MCP framework.
Last updated -
1
MIT License
Everything MCP Server
infinitum-nihil
-
security
F
license
-
quality
A test MCP server implementing all protocol features including tools, resources, prompts, and sampling to help developers build and test MCP clients.
Last updated -

View all related MCP servers

MCP Echo Service

MCP Echo Service

Features

Quick Start

Local Development

Docker

MCP Protocol Support

Session Management

API Usage

Complete MCP Example

Simple Health Check

Development

Testing

Building and Deployment

Contributing

About

License

Related MCP Servers

MCP Everything

Echo MCP Server

MCP Perplexity Server

Everything MCP Server

New MCP Servers

MCP directory API