# MCP Echo Service
[](https://github.com/nimbletoolsinc/mcp-registry)
[](https://www.nimblebrain.ai)
[](https://www.nimblebrain.ai/discord?utm_source=github&utm_medium=readme&utm_campaign=mcp-echo&utm_content=discord-badge)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/NimbleBrainInc/mcp-echo/actions)
## About
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
```bash
# 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 -m mcp_echo.server
# Or run via FastMCP
uv run fastmcp run src/mcp_echo/server.py
```
The server will start on `http://localhost:8000` with:
- Health check: `GET /health`
- MCP endpoint: `POST /mcp`
### Building MCPB Bundle
This server is distributed as an MCPB bundle. To build locally:
```bash
# Install mcpb CLI (requires Node.js)
npm install -g @anthropic-ai/mcpb
# Build the bundle
mcpb pack . mcp-echo.mcpb
```
## 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
- **Python Version**: 3.13+
### Session Management
The server requires proper MCP initialization:
1. **Initialize**: Send `initialize` request to establish session
2. **Initialized**: Send `notifications/initialized` notification
3. **Tools**: Use session ID for all subsequent requests
## API Usage
### Complete MCP Example
```bash
# 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
}'
```
### Simple Health Check
```bash
curl http://localhost:8000/health
```
## Development
### Testing
```bash
# Install with dev dependencies
uv sync --group dev
# Run unit tests
uv run pytest tests/
# Run with coverage
uv run pytest tests/ --cov=mcp_echo
```
### E2E Tests
E2E tests require the [mcpb CLI](https://github.com/modelcontextprotocol/mcpb) and Docker:
```bash
# Install mcpb CLI
npm install -g @anthropic-ai/mcpb
# Run e2e tests
uv run pytest e2e/
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## About
Part of the [NimbleTools](https://www.nimbletools.ai) ecosystem.
From the makers of [NimbleBrain](https://www.nimblebrain.ai).
## License
MIT License - see LICENSE file for details.
## Links
Part of the [NimbleTools Registry](https://github.com/nimbletoolsinc/mcp-registry), an open source collection of production-ready MCP servers. For enterprise deployment, check out [NimbleBrain](https://www.nimblebrain.ai).
- [MCPB CLI](https://github.com/modelcontextprotocol/mcpb)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [MCP Documentation](https://modelcontextprotocol.io)
