Cómo construir un servidor MCP (Protocolo de Contexto de Modelo): Una guía para principiantes

Imagina darle a tu asistente de IA la capacidad de obtener datos meteorológicos, analizar precios de acciones o automatizar tareas, todo a través de un único protocolo. El Model Context Protocol (MCP) hace esto posible, y con el nuevo MCP Framework, construir tu propio servidor es más fácil que nunca.

En esta guía, te guiaré a través de la creación de un servidor MCP utilizando las herramientas CLI del MCP Framework. No se necesita experiencia previa en MCP, ¡solo conocimientos básicos de JavaScript/TypeScript y una pizca de curiosidad!

💡

¿Listo para llevar tu desarrollo de MCP al siguiente nivel? Descarga Apidog gratis hoy y descubre cómo puede transformar tu flujo de trabajo.

button

Entendiendo MCP

Antes de sumergirnos en la configuración, cubramos rápidamente qué es MCP y por qué es importante:

Descripción general de MCP: The Model Context Protocol es una especificación abierta creada por Anthropic para estandarizar cómo los modelos de IA interactúan con fuentes de datos externas. Permite a los desarrolladores construir herramientas que se pueden integrar fácilmente con plataformas de IA como Claude Desktop.

Beneficios de MCP: MCP simplifica el proceso de integración al proporcionar un protocolo estandarizado para el desarrollo de herramientas. Esto significa que puedes concentrarte en construir herramientas sin preocuparte por problemas de compatibilidad entre diferentes plataformas.

Construyendo tu primer servidor MCP

Paso 1: Lo que necesitarás

Antes de comenzar, asegúrate de tener lo siguiente instalado:

Node.js (20 o superior): El servidor está construido en Node.js, por lo que necesitarás tenerlo instalado. Descargar aquí
TypeScript (5.0 o posterior): Esto se utiliza para construir tu servidor.
npm: Un administrador de paquetes para manejar las dependencias.
MCP Framework: Esto se puede instalar globalmente a través de npm o agregar a un proyecto existente.
10 minutos de paciencia: En serio, es así de rápido

Paso 2: Instala el MCP Framework

Hay dos formas de comenzar con el MCP Framework:

Opción 1: Usando el CLI de MCP (Recomendado)

La forma más fácil de configurar un servidor MCP es usando el CLI. Aquí te mostramos cómo hacerlo:

# Install the CLI globally  
npm install -g mcp-framework  

# Create a new project  
mcp create my-mcp-server  

# Navigate to your project  
cd my-mcp-server  

# Install dependencies  
npm install

Esto crea un servidor MCP listo para usar con: TypeScript preconfigurado, herramientas de ejemplo y manejo de errores incorporado. Debería verse algo así:

Ahora, tu nuevo proyecto MCP está listo para funcionar.

Opción 2: Instalación manual (Para proyectos existentes)

Si deseas agregar el MCP Framework a un proyecto existente, sigue estos pasos:

Instala el MCP Framework:

npm install mcp-framewor

Crea un servidor básico dentro del archivo src/index.ts:

import { MCPServer } from "mcp-framework";  

const server = new MCPServer();  

server.start().catch((error) => {  
  console.error("Server error:", error);  
  process.exit(1);  
});

Paso 3: Creando tu primera herramienta (Ejemplo del clima)

Ahora que tu servidor está configurado, construyamos una herramienta del clima que obtenga información meteorológica para una ciudad dada.

Crea una nueva herramienta:

Usando el CLI de MCP, puedes crear una nueva herramienta para información meteorológica:

mcp add tool weather

Esto generará un archivo llamado src/tools/WeatherTool.ts. Alternativamente, podrías simplemente crear ese archivo manualmente. Ahora, editemos ese archivo.

Modifica la herramienta del clima:

Abre el archivo WeatherTool.ts y actualízalo de la siguiente manera:

import { MCPTool } from "mcp-framework";  
import { z } from "zod";  

interface WeatherInput {  
  city: string;  
}  

class WeatherTool extends MCPTool<WeatherInput> {  
  name = "weather";  
  description = "Get weather information for a city";  

  // Schema validation using Zod  
  schema = {  
    city: {  
      type: z.string(),  
      description: "City name (e.g., London)",  
    },  
  };  

  async execute({ city }: WeatherInput) {  
    // Replace this with a real API call  
    return {  
      city,  
      temperature: 22,  
      condition: "Sunny",  
      humidity: 45,  
    };  
  }  
}  

export default WeatherTool;

En este código, definimos una clase WeatherTool que obtiene el clima para una ciudad. Si bien esta implementación simulada devuelve datos estáticos, puedes reemplazarla con una llamada API real.

Paso 4: Construye y prueba tu servidor MCP

Después de modificar la herramienta del clima, es hora de construir y probar para ver si tu servidor MCP funciona como se espera, y para eso utilizaremos el inspector MCP.

Construye el proyecto:

npm run build

Elige un método de transporte: MCP Framework admite dos transportes:

Transporte STDIO: Mejor para CLI e integraciones locales.
Transporte SSE: Ideal para aplicaciones web y sistemas distribuidos.

Para este tutorial, usaremos el Transporte STDIO, que es perfecto para pruebas locales.

Inicia el Inspector MCP: usa el siguiente comando:

npx @modelcontextprotocol/inspector dist/index.js

Prueba la herramienta del clima:

Para probar tu herramienta del clima, selecciona la herramienta weather e ingresa una ciudad como "Paris".

Luego, mira los datos meteorológicos simulados.

Paso 5: Conecta el MCP a datos meteorológicos reales

Actualicemos nuestra herramienta del clima para usar la API gratuita de Open-Meteo, una alternativa poderosa que proporciona pronósticos hiperlocales sin claves API. Para comenzar, puedes crear una nueva herramienta y darle un nuevo nombre o simplemente reemplazar el código de las herramientas antiguas con el nuevo código a continuación:

import { MCPTool } from "mcp-framework";
import { z } from "zod";
import axios, { AxiosError } from "axios";

interface WeatherApiInput {
  city: string;
}

interface WeatherApiResponse {
  city: string;
  temperature: number;
  condition: string;
  humidity: number;
  windSpeed: number;
  feelsLike: number;
  precipitation: number;
}

class WeatherApiTool extends MCPTool<WeatherApiInput> {
  name = "weather_api";
  description = "Get real weather information for a city using Open-Meteo API";

  private readonly GEOCODING_URL = "https://geocoding-api.open-meteo.com/v1/search";
  private readonly WEATHER_URL = "https://api.open-meteo.com/v1/forecast";

  schema = {
    city: {
      type: z.string(),
      description: "City name to get weather for",
    },
  };

  async execute({ city }: WeatherApiInput): Promise<WeatherApiResponse> {
    try {
      // First, get coordinates for the city
      const geoResponse = await axios.get(this.GEOCODING_URL, {
        params: {
          name: city,
          count: 1,
          language: "en",
          format: "json"
        }
      });

      if (!geoResponse.data.results?.length) {
        throw new Error(`City '${city}' not found`);
      }

      const location = geoResponse.data.results[0];
      
      // Then get weather data using coordinates
      const weatherResponse = await axios.get(this.WEATHER_URL, {
        params: {
          latitude: location.latitude,
          longitude: location.longitude,
          current: ["temperature_2m", "relative_humidity_2m", "apparent_temperature", "precipitation", "weather_code", "wind_speed_10m"],
          timezone: "auto"
        }
      });

      const current = weatherResponse.data.current;
      
      // Map weather code to condition
      const condition = this.getWeatherCondition(current.weather_code);

      return {
        city: location.name,
        temperature: Math.round(current.temperature_2m),
        condition,
        humidity: Math.round(current.relative_humidity_2m),
        windSpeed: Math.round(current.wind_speed_10m),
        feelsLike: Math.round(current.apparent_temperature),
        precipitation: current.precipitation
      };
    } catch (error: unknown) {
      if (error instanceof Error) {
        throw new Error(`Failed to fetch weather data: ${error.message}`);
      }
      throw new Error('Failed to fetch weather data: Unknown error occurred');
    }
  }

  private getWeatherCondition(code: number): string {
    // WMO Weather interpretation codes (https://open-meteo.com/en/docs)
    const conditions: Record<number, string> = {
      0: "Clear sky",
      1: "Mainly clear",
      2: "Partly cloudy",
      3: "Overcast",
      45: "Foggy",
      48: "Depositing rime fog",
      51: "Light drizzle",
      53: "Moderate drizzle",
      55: "Dense drizzle",
      61: "Slight rain",
      63: "Moderate rain",
      65: "Heavy rain",
      71: "Slight snow",
      73: "Moderate snow",
      75: "Heavy snow",
      77: "Snow grains",
      80: "Slight rain showers",
      81: "Moderate rain showers",
      82: "Violent rain showers",
      85: "Slight snow showers",
      86: "Heavy snow showers",
      95: "Thunderstorm",
      96: "Thunderstorm with slight hail",
      99: "Thunderstorm with heavy hail"
    };
    
    return conditions[code] || "Unknown";
  }
}

export default WeatherApiTool;

El código es un poco largo, pero por ahora concéntrate en hacer que el código funcione y en la sensación de comenzar con MCP. Tómate tu tiempo y utiliza esto como una guía de ejemplo para ayudarte a hacer la transición a la construcción de MCP aún más complejos.

Para probar la herramienta, simplemente selecciónala:

Ingresa una ciudad, por ejemplo, "Lusaka", y mira los resultados:

¡Esperemos que en esta etapa hayas superado la mayoría de los problemas de configuración y ejecución del proyecto, por lo que probar la nueva herramienta MCP no debería ser un desafío en absoluto!

Trabajando con Apidog

No olvides impulsar el desarrollo de tu servidor MCP con Apidog, una herramienta versátil que simplifica las pruebas de API, la simulación y la documentación. Comienza registrándote en su nivel gratuito, luego crea un proyecto para centralizar tus flujos de trabajo de API. Importa tus endpoints para monitorear las solicitudes, simula respuestas con servidores mock inteligentes y automatiza las pruebas para detectar errores ocultos de forma temprana. Apidog agiliza la depuración y garantiza que tus herramientas funcionen a la perfección, lo que lo convierte en el compañero perfecto para construir integraciones de IA robustas.

Conclusión

Construir un Servidor MCP es un proceso sencillo que puede mejorar significativamente tus flujos de trabajo de IA. Al integrar herramientas como Apidog, puedes optimizar tu proceso de desarrollo, asegurando API robustas y bien documentadas. Ya sea que estés trabajando con servicios web o archivos locales, MCP proporciona una forma estandarizada de conectar modelos de IA con fuentes de datos externas.

¿Listo para llevar tu flujo de trabajo de desarrollo de API al siguiente nivel? Descarga Apidog gratis hoy y descubre cómo puede transformar tu flujo de trabajo.

button