mcp-server-streamable-http-demo

andkirby/mcp-server-streamable-http-demo

3.1

If you are the rightful owner of mcp-server-streamable-http-demo and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This is a simple MCP server implementing the MCP Streamable HTTP Protocol using FastAPI, providing JSON-RPC 2.0 endpoints for AI assistants.

MCP HTTP Server with Streamable HTTP Protocol

Simple MCP server implementing the MCP Streamable HTTP Protocol (2025-03-26) with FastAPI. Provides JSON-RPC 2.0 endpoints for AI assistants to discover and call tools over HTTP transport.

Quick Start

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn server:app --reload

Testing

MCP Inspector CLI

# List tools
timeout 10 npx @modelcontextprotocol/inspector --cli http://localhost:8000/mcp --transport http --method tools/list

# Call hello tool
timeout 10 npx @modelcontextprotocol/inspector --cli http://localhost:8000/mcp --transport http --method tools/call --tool-name hello --tool-arg name=FooBar --log-level debug

curl

# List tools
curl -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' http://localhost:8000/mcp

# Call hello tool
curl -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"hello","arguments":{"name":"World"}}}' http://localhost:8000/mcp

# Health check
curl http://localhost:8000/health

Features

  • MCP Streamable HTTP Protocol (2025-03-26) compliant
  • JSON-RPC 2.0 communication over HTTP
  • Tool Discovery with pagination support
  • Tool Execution with proper error handling
  • Lifecycle Management (initialize → operate → shutdown)
  • Logging Support with RFC 5424 log levels
  • Health Monitoring endpoint

API

  • POST /mcp - JSON-RPC 2.0 endpoint
    • initialize - Protocol negotiation and capability exchange
    • tools/list - Tool discovery with pagination
    • tools/call - Tool execution with error handling
    • logging/setLevel - Configure log verbosity
  • GET /health - Health check endpoint

MCP Protocol Compliance

✅ Lifecycle Management - Proper initialization sequence and state management ✅ Tools Specification - Tool discovery, execution, and error handling ✅ Logging Specification - RFC 5424 log levels and structured messages ✅ Error Handling - Protocol vs execution error distinction ✅ JSON-RPC 2.0 - Standard request/response format

Dependencies

  • FastAPI >= 0.104.0
  • Uvicorn >= 0.24.0
  • Python 3.8+