MCP Simple Server

Un servidor MCP simple con transporte HTTP transmisible que admite herramientas matemáticas básicas como suma y multiplicación.

GitHub
1
Prueba este MCPPatrocinado

Documentación

MCP Simple Server

Una implementación mínima y de referencia de un servidor del Model Context Protocol con transporte HTTP transmisible por streaming. Construido con FastMCP siguiendo la especificación oficial de MCP de Anthropic 2025-06-18. Punto de partida perfecto para crear servidores MCP remotos.

🎯 Propósito

Este proyecto sirve como una referencia simple y bien documentada para desarrolladores que quieran:

  • Crear su primer servidor MCP
  • Desplegar servidores MCP en plataformas en la nube (Railway, Heroku, Render)
  • Entender la implementación del protocolo MCP
  • Crear una base para soluciones MCP más sofisticadas

Características

  • ✅ Dos herramientas matemáticas: funciones add y multiply
  • ✅ Transporte HTTP transmisible por streaming: protocolo MCP moderno con soporte SSE
  • ✅ Gestión de sesiones: flujo de inicialización MCP adecuado
  • ✅ Despliegue remoto: configuraciones de despliegue para Railway, Heroku y Render
  • ✅ Pruebas automatizadas: herramientas completas de validación y depuración del protocolo
  • ✅ Integración con Claude Desktop: listo para la integración con asistentes de IA
  • ✅ Implementación de referencia: código bien documentado para aprender

Inicio rápido

Desarrollo local

git clone https://github.com/oleksandrsirenko/mcp-simple-server.git
cd mcp-simple-server
uv sync
source .venv/bin/activate
python main.py

El servidor se inicia en: http://localhost:8000/mcp/

Probar el servidor

python test_server.py

Salida esperada:

🧪 Starting MCP Server Tests
✅ Initialize successful - Server: Simple Server
✅ Initialized notification sent
✅ Found 2 tools: add, multiply  
✅ Add tool returned correct result
✅ Multiply tool returned correct result
🎉 All tests passed!

Herramientas disponibles

add(a, b)

Suma dos números.

Ejemplo:

{"name": "add", "arguments": {"a": 25, "b": 17}}
→ Returns: 42

multiply(a, b)

Multiplica dos números.

Ejemplo:

{"name": "multiply", "arguments": {"a": 8, "b": 6}}
→ Returns: 48

Pruebas manuales con curl

Pruebas locales (desarrollo)

Para probar tu servidor de desarrollo local que se ejecuta en localhost:8000:

1. Inicializar la sesión

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

2. Enviar la notificación de inicialización

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

3. Listar herramientas

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

4. Llamar a la herramienta Add

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add","arguments":{"a":25,"b":17}}}'

Pruebas remotas (producción)

Para probar tu servidor desplegado, reemplaza localhost:8000 con la URL de tu despliegue:

# Example with Railway deployment
curl -X POST https://your-app.railway.app/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

Nota: Para pruebas remotas exhaustivas, usa el script de prueba automatizado:

python test_deployment.py your-app.railway.app

Despliegue

Railway (recomendado)

  1. Haz push a GitHub:

    git add .
git commit -m "ready for deployment"
git push origin main

  2. Despliega en Railway:

    • Ve a railway.app
    • Haz clic en "Deploy from GitHub repo"
    • Selecciona tu repositorio
    • Railway detecta automáticamente el Dockerfile y despliega

  3. Prueba tu despliegue:

    python test_deployment.py your-app-name.up.railway.app

  4. Tu URL de MCP: https://your-app.railway.app/mcp/

Heroku

heroku create your-mcp-server
git push heroku main

Tu URL de MCP: https://your-mcp-server.herokuapp.com/mcp/

Render

  1. Conecta el repositorio de GitHub a Render
  2. Render detecta automáticamente render.yaml y el Dockerfile
  3. Despliega automáticamente

Tu URL de MCP: https://your-service.onrender.com/mcp/

Docker

docker build -t mcp-simple-server .
docker run -p 8000:8000 mcp-simple-server

Integración con Claude Desktop

Configuración del servidor local

{
  "mcpServers": {
    "simple-server": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/mcp-simple-server"
    }
  }
}

Configuración del servidor remoto (recomendada)

Para servidores remotos desplegados en Railway, Heroku o Render, usa el paquete mcp-remote:

{
  "mcpServers": {
    "simple-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-app.railway.app/mcp/",
        "--allow-http",
        "--header",
        "Accept: application/json, text/event-stream"
      ]
    }
  }
}

Notas clave de configuración:

  • Usa npx con la bandera -y para instalar automáticamente mcp-remote
  • Incluye la barra diagonal final en la URL: /mcp/
  • Añade la bandera --allow-http para conexiones HTTP
  • Incluye el encabezado Accept para un soporte SSE adecuado

Alternativa: proxy Python directo (avanzado)

Para usuarios avanzados o con fines de depuración, puedes crear un proxy Python personalizado:

{
  "mcpServers": {
    "simple-server-proxy": {
      "command": "python",
      "args": ["claude_mcp_proxy.py"],
      "cwd": "/path/to/mcp-simple-server"
    }
  }
}

Nota: Esto requiere el script claude_mcp_proxy.py del repositorio y es principalmente para fines de depuración. Usa mcp-remote para producción.

Ubicaciones de los archivos de configuración:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Prueba con Claude

Después de la integración, pregúntale a Claude:

  • "¿Puedes sumar 42 y 18 por mí?"
  • "¿Cuánto es 7 por 9?"
  • "¿Qué herramientas tienes disponibles?"

¡Claude usará tu servidor MCP para hacer los cálculos! 🎉

Desarrollo

Añadir nuevas herramientas

@mcp.tool()
def subtract(a: float, b: float) -> float:
    """Subtract two numbers"""
    return a - b

@mcp.tool()
def divide(a: float, b: float) -> float:
    """Divide two numbers"""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

Variables de entorno

  • HOST: host del servidor (por defecto: 127.0.0.1, usa 0.0.0.0 para despliegue)
  • PORT: puerto del servidor (por defecto: 8000, Railway lo establece automáticamente)
HOST=0.0.0.0 PORT=3000 python main.py

Nota: Para el despliegue en Railway, FastMCP se vinculará automáticamente a 0.0.0.0:$PORT.

Estructura del proyecto

mcp-simple-server/
├── main.py                    # MCP server (~25 lines)
├── test_server.py             # Local server tests (~300 lines)
├── test_deployment.py         # Remote deployment tests
├── test_host_binding.py       # Host binding tests
├── test_proxy_script.py       # Proxy testing script
├── test_streamable_app.py     # Streamable HTTP tests
├── test_tool_verification.py  # Tool verification tests
├── debug_railway_server.py    # Railway debugging utilities
├── debug_fastmcp.py           # FastMCP debugging utilities
├── claude_mcp_proxy.py        # Claude Desktop proxy (optional)
├── start.sh                   # Shell startup script
├── pyproject.toml             # Project configuration
├── README.md                  # This documentation
├── uv.lock                    # Dependency lock file
├── .gitignore                 # Git ignore patterns
├── .python-version            # Python version specification
├── Dockerfile                 # Docker deployment
├── railway.toml               # Railway configuration
├── Procfile                   # Heroku configuration
└── render.yaml                # Render configuration

Arquitectura

  • FastMCP: implementación MCP de alto nivel de Anthropic
  • HTTP transmisible por streaming: transporte moderno con soporte de streaming SSE
  • Gestión de sesiones: conexiones con estado e identificadores de sesión
  • JSON-RPC 2.0: protocolo estándar para el intercambio de mensajes
  • Protocolo 2025-06-18: especificación MCP más reciente
  • Puerto 8000: puerto predeterminado del servidor FastMCP (configurable mediante la variable de entorno PORT)

Detalles técnicos

Implementación del servidor

  • Framework: FastMCP (biblioteca oficial de Anthropic)
  • Transporte: HTTP transmisible por streaming con Server-Sent Events
  • Protocolo: especificación MCP 2025-06-18
  • Dependencias: httpx>=0.28.1, mcp>=1.9.4

Flujo del protocolo MCP

  1. El cliente envía la solicitud initialize
  2. El servidor responde con las capacidades y el identificador de sesión
  3. El cliente envía la notificación initialized
  4. Comienzan las operaciones normales (tools/list, tools/call, etc.)

Formato de respuesta de las herramientas

Las herramientas devuelven valores simples de Python (float, int, str) que FastMCP envuelve automáticamente en el formato de respuesta MCP adecuado.

Solución de problemas

El servidor no se inicia

# Check if port is in use
lsof -i :8000

# Try different port
PORT=3000 python main.py

Errores del protocolo MCP

# Run automated test
python test_server.py

# Check server logs for detailed errors

Claude Desktop no se conecta

  1. Verifica la sintaxis de la configuración JSON: usa un validador de JSON
  2. Comprueba la accesibilidad de la URL del servidor: pruébalo con curl o el navegador
  3. Reinicia Claude Desktop después de los cambios de configuración
  4. Asegúrate de usar la ruta de endpoint MCP correcta: usa /mcp/ con barra diagonal final
  5. Usa mcp-remote para servidores remotos: no uses curl para conexiones remotas

Probar el despliegue remoto

Prueba tu servidor desplegado con el script proporcionado:

# Test your deployed server (replace with your URL)
python test_deployment.py your-app.railway.app

# Or with full URL
python test_deployment.py https://your-app.railway.app

Esto ejecutará el conjunto completo de pruebas del protocolo MCP contra tu servidor remoto.

Problemas comunes

  • Endpoint incorrecto: usa /mcp/ (con barra diagonal final)
  • Encabezados faltantes: incluye todos los encabezados MCP requeridos
  • Gestión de sesiones: debes enviar la notificación initialized después de initialize
  • Conexiones remotas: usa mcp-remote, no curl para Claude Desktop
  • Vinculación de puerto: usa 0.0.0.0:$PORT para despliegue, no 127.0.0.1

Dependencias

dependencies = [
    "httpx>=0.28.1",   # HTTP client for testing
    "mcp>=1.9.4",      # Official Anthropic MCP library
]

El proyecto usa:

  • mcp: SDK oficial de Python para MCP de Anthropic
  • httpx: cliente HTTP moderno para pruebas automatizadas
  • Python: requiere Python >=3.10

Contribuciones

  1. Haz un fork del repositorio
  2. Realiza tus cambios
  3. Ejecuta las pruebas: python test_server.py
  4. Prueba el despliegue: python test_deployment.py your-test-url
  5. Asegúrate de que todas las pruebas pasen
  6. Envía una solicitud de extracción (pull request)

Licencia

Licencia MIT

Recursos