Wylcetal MCP

Servidor MCP Remoto con Python

Este proyecto demuestra cómo crear y desplegar servidores MCP (Model Context Protocol) remotos utilizando Python, FastMCP y FastAPI.

📋 Descripción

El proyecto incluye:

• Un servidor MCP simple que realiza búsquedas web usando la API de Tavily
• Múltiples servidores MCP combinados en una sola aplicación FastAPI
• Configuración para despliegue en Render.com

🛠️ Tecnologías Utilizadas

• Python 3.11+
• FastMCP: Framework para crear servidores MCP
• FastAPI: Framework web para Python
• Tavily API: API de búsqueda web
• uv: Gestor de paquetes moderno para Python
• python-dotenv: Gestión de variables de entorno

📦 Instalación de Dependencias

1. Instalar uv (Gestor de Paquetes)

# En Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# En macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Sincronizar Dependencias

# Iniciar un proyecto con uv
uv init

# Instalar todas las dependencias del proyecto
uv sync

# Instalar dependencias
uv add 

3. Configurar Variables de Entorno

Crea un archivo .env en la raíz del proyecto:

TAVILY_API_KEY=tu_api_key_aqui

Nota: Obtén tu API key de Tavily en https://tavily.com

🚀 Servidor MCP Simple (server.py)

Descripción

El archivo server.py implementa un servidor MCP básico con una herramienta de búsqueda web.

Características:

• Herramienta: web_search(query: str) - Realiza búsquedas web usando Tavily API
• Transporte: HTTP
• Puerto: 3000
• Host: localhost

Código Principal

from fastmcp import FastMCP
from tavily import TavilyClient

# Crear servidor MCP
mcp = FastMCP(name="web-search")

# Definir herramienta
@mcp.tool()
def web_search(query: str) -> List[Dict]:
    """Busca información en la web usando Tavily API"""
    response = tavily_client.search(query)
    return response["results"]

Ejecutar el Servidor

# Ejecutar directamente
uv run server.py

# El servidor estará disponible en http://localhost:3000

Debugging con MCP Inspector

# Instalar MCP Inspector (si no lo tienes)
npm install -g @modelcontextprotocol/inspector

# Ejecutar con Inspector
npx @modelcontextprotocol/inspector python server.py

El Inspector abrirá una interfaz web donde podrás:

• Ver las herramientas disponibles
• Probar la herramienta web_search
• Inspeccionar requests y responses
• Debugear errores

🔧 Servidores MCP Múltiples (fastapi_example/)

Arquitectura

El directorio fastapi_example/ contiene una implementación avanzada que combina múltiples servidores MCP en una sola aplicación FastAPI.

1. Echo Server (echo_server.py)

Servidor simple que devuelve el mensaje recibido.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP(name="EchoServer", stateless_http=True)

@mcp.tool(description="A simple echo tool")
def echo(message: str) -> str:
    return f"Echo: {message}"

Herramienta:

• echo(message: str) - Devuelve el mensaje con prefijo "Echo:"

2. Math Server (math_server.py)

Servidor con operaciones matemáticas básicas.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP(name="MathServer", stateless_http=True)

@mcp.tool(description="A simple add tool")
def add_two(n: int) -> int:
    return n + 2

Herramienta:

• add_two(n: int) - Suma 2 al número proporcionado

3. Servidor Principal (server.py)

Combina múltiples servidores MCP usando FastAPI.

from contextlib import asynccontextmanager, AsyncExitStack
from fastapi import FastAPI
from echo_server import mcp as echo_mcp
from math_server import mcp as math_mcp

# Gestión del ciclo de vida
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with AsyncExitStack() as stack:
        await stack.enter_async_context(echo_mcp.session_manager.run())
        await stack.enter_async_context(math_mcp.session_manager.run())
        yield

# Crear aplicación FastAPI
app = FastAPI(lifespan=lifespan)

# Montar servidores MCP en diferentes rutas
app.mount("/echo", echo_mcp.streamable_http_app())
app.mount("/math", math_mcp.streamable_http_app())

Características:

• Gestión de sesiones: Usa AsyncExitStack para manejar múltiples session managers
• Rutas separadas: Cada servidor MCP tiene su propia ruta
• Puerto configurable: Lee la variable de entorno PORT (default: 10000)

Ejecutar Servidores Múltiples

# Desde la raíz del proyecto
uv run fastapi_example/server.py

Endpoints disponibles:

• http://localhost:10000/echo - Echo Server
• http://localhost:10000/math - Math Server

Probar con MCP Inspector

# Para Echo y Math Server
npx @modelcontextprotocol/inspector http://localhost:10000/mcp

🌐 Deploy en Render.com

Paso 1: Preparar el Proyecto

Asegúrate de tener estos archivos:

• pyproject.toml - Dependencias del proyecto
• fastapi_example/server.py - Aplicación principal
• .gitignore - Archivos a ignorar

Paso 2: Crear Servicio en Render

1. Ve a Render.com y crea una cuenta
2. Click en "New +" → "Web Service"
3. Conecta tu repositorio de GitHub/GitLab
4. Configura el servicio:

Configuración:

Name: mcp-remote-server
Environment: Python 3
Build Command: uv sync
Start Command: uv run fastapi_example/server.py

Paso 3: Variables de Entorno

En la sección "Environment" de Render, agrega:

TAVILY_API_KEY=tu_api_key_de_tavily
PORT=10000

Nota: Render asigna automáticamente la variable PORT, pero puedes especificar un valor por defecto.

Paso 4: Deploy

1. Click en "Create Web Service"
2. Render automáticamente:

- Clonará tu repositorio - Instalará dependencias - Iniciará el servidor

1. Obtendrás una URL pública como: https://tu-app.onrender.com

Endpoints en Producción

Una vez desplegado, tus servidores MCP estarán disponibles en:

https://tu-app.onrender.com/echo/mcp/
https://tu-app.onrender.com/math/mcp/

Conectar desde VsCode

Edita tu configuración de VsCode (.vscode/mcp.json):

{
  "servers": {
    "tavilySearch": {
      "url": "https://mcp-streamable-http-33rv.onrender.com/echo/mcp/",
      "type": "http"
    }
  }
}

Conectar desde KiloCode

Edita tu configuración de VsCode (.kilocode/mcp.json):

{
  "mcpServers": {
    "web-search": {
      "type": "streamable-http",
      "url": "https://mcp-streamable-http-33rv.onrender.com/echo/mcp",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

🧪 Pruebas y Debugging

Probar Localmente

# Terminal 1: Iniciar servidor
uv run fastapi_example/server.py

# Terminal 2: Probar con curl
curl -X POST http://localhost:10000/echo \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello World"}'

curl -X POST http://localhost:10000/math \
  -H "Content-Type: application/json" \
  -d '{"n": 5}'

Usar MCP Inspector

El MCP Inspector es una herramienta visual para debugear servidores MCP:

# Servidor simple
npx @modelcontextprotocol/inspector python server.py

# Servidor remoto
npx @modelcontextprotocol/inspector http://localhost:10000/echo

Funcionalidades del Inspector:

• ✅ Lista de herramientas disponibles
• ✅ Interfaz para probar herramientas
• ✅ Visualización de requests/responses
• ✅ Logs en tiempo real
• ✅ Validación de esquemas

Logs en Render

Para ver logs en producción:

1. Ve a tu servicio en Render Dashboard
2. Click en "Logs"
3. Verás logs en tiempo real de tu aplicación

📁 Estructura del Proyecto

29_MCP_Remote/
├── .env                      # Variables de entorno (no incluir en git)
├── .gitignore               # Archivos ignorados por git
├── .python-version          # Versión de Python
├── pyproject.toml           # Dependencias y configuración
├── uv.lock                  # Lock file de dependencias
├── README.md                # Este archivo
├── server.py                # Servidor MCP simple con Tavily
└── fastapi_example/
    ├── echo_server.py       # Servidor MCP de eco
    ├── math_server.py       # Servidor MCP matemático
    └── server.py            # Aplicación FastAPI multi-MCP

🔑 Variables de Entorno

📚 Recursos Adicionales

• Documentación de FastMCP
• Model Context Protocol
• Tavily API
• FastAPI Documentation
• Render Documentation

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto es de código abierto y está disponible bajo la licencia MIT.

✨ Características Destacadas

• ✅ Servidores MCP con transporte HTTP
• ✅ Integración con APIs externas (Tavily)
• ✅ Múltiples servidores en una sola aplicación
• ✅ Gestión moderna de dependencias con uv
• ✅ Deploy sencillo en Render.com
• ✅ Debugging con MCP Inspector
• ✅ Configuración mediante variables de entorno
• ✅ Código limpio y bien documentado

🐛 Troubleshooting

Error: TAVILY_API_KEY not set

Solución: Asegúrate de tener el archivo .env con tu API key:

echo "TAVILY_API_KEY=tu_api_key" > .env

Error: Port already in use

Solución: Cambia el puerto en el código o mata el proceso:

# Windows
netstat -ano | findstr :3000
taskkill /PID 
 /F

# Linux/Mac
lsof -ti:3000 | xargs kill -9

Error al instalar dependencias

Solución: Actualiza uv y vuelve a sincronizar:

uv self update
uv sync --reinstall

Desarrollado con ❤️ usando Python y FastMCP