Cómo construí un servidor MCP conectado a Claude Desktop con Typescript

El Protocolo de Contexto del Modelo (MCP, por sus siglas en inglés) representa un avance significativo en la forma en que los asistentes de IA interactúan con herramientas y fuentes de datos externas. Desarrollado por Anthropic, MCP permite a Claude comunicarse sin problemas con servidores personalizados, lo que le permite acceder a información en tiempo real, ejecutar flujos de trabajo complejos e interactuar con las API sin salir del contexto de la conversación. Esta capacidad transforma a Claude de un LLM independiente en un asistente versátil que puede aprovechar la funcionalidad externa manteniendo la coherencia de la conversación.

En esta guía completa, lo guiaremos a través del proceso de creación de un servidor TypeScript MCP desde cero y lo conectaremos a Claude Desktop. Al implementar esta integración, permitirá a Claude realizar tareas como recuperar datos en tiempo real, ejecutar cálculos o interactuar con su lógica empresarial personalizada directamente dentro de las conversaciones.

Antes de sumergirnos en la implementación de nuestro servidor MCP, vale la pena mencionar que su elección de herramienta de desarrollo de API puede afectar significativamente la eficiencia de su flujo de trabajo.

Si bien Postman ha sido durante mucho tiempo el estándar de la industria, Apidog ha surgido como una alternativa superior que complementa perfectamente los flujos de trabajo de desarrollo modernos como el que estamos construyendo.
A diferencia de las limitaciones de Postman con las API en desarrollo, Apidog ofrece sincronización en tiempo real entre sus especificaciones y solicitudes de API, lo que garantiza que su documentación y pruebas se mantengan automáticamente actualizadas a medida que evolucionan sus API.
Con la creación visual de especificaciones de API, ejecuciones de colecciones ilimitadas (en comparación con el límite de 25/mes de Postman) y funciones potentes como solicitudes autogeneradas y respuestas simuladas, Apidog agiliza todo el ciclo de vida de la API. Sus capacidades integrales de prueba, incluida la creación de pruebas visuales y los ejecutores autoalojados, lo hacen ideal para equipos que implementan integraciones complejas como nuestro servidor MCP.

A medida que construimos nuestro servidor TypeScript MCP, considere cómo las funciones de colaboración y el enfoque centrado en el desarrollo de Apidog pueden mejorar la productividad de su equipo y garantizar que sus API sigan siendo coherentes, estén bien probadas y estén completamente documentadas durante todo el proceso.

button

Comprensión del Protocolo de Contexto del Modelo

El Protocolo de Contexto del Modelo define una forma estandarizada para que Claude se comunique con servicios externos. Cuando Claude identifica que necesita información de una fuente externa, puede invocar un servidor MCP a través de una solicitud JSON con un formato especial. El servidor procesa esta solicitud y devuelve los datos solicitados, que Claude puede incorporar a su respuesta.

MCP ofrece varias ventajas sobre los enfoques de integración de IA tradicionales:

Conciencia contextual: Claude mantiene el historial completo de la conversación al realizar solicitudes
Comunicación bidireccional: El protocolo admite interacciones complejas entre Claude y su servidor
Seguridad y control: Usted determina qué funcionalidad exponer y cómo se procesan las solicitudes
Experiencia perfecta: Los usuarios interactúan con Claude de forma natural sin necesidad de conocer las integraciones subyacentes

Requisitos previos

Antes de comenzar a construir nuestro servidor MCP, asegúrese de tener lo siguiente:

Node.js (v18 o posterior) instalado
Un editor de código como Visual Studio Code
Conocimientos básicos de TypeScript
Aplicación Claude Desktop instalada
Familiaridad con Express.js (para construir los puntos finales del servidor)

Configuración de su proyecto TypeScript

Comencemos creando un nuevo proyecto TypeScript para nuestro servidor MCP:

mkdir claude-mcp-server
cd claude-mcp-server
npm init -y
npm install typescript @types/node ts-node express @types/express cors @types/cors
npx tsc --init

A continuación, actualice su tsconfig.json para incluir esta configuración:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Implementación del servidor MCP

Cree un nuevo archivo llamado server.ts en el directorio raíz de su proyecto. Este será el punto de entrada para nuestro servidor MCP:

import express from 'express';
import cors from 'cors';
import { Request, Response } from 'express';

// Define types for the MCP protocol
interface MCPRequest {
  query: string;
  conversation_id: string;
  request_id: string;
  parameters?: Record<string, any>;
}

interface MCPResponse {
  response: string;
  status: 'success' | 'error';
  error?: string;
}

const app = express();
app.use(cors());
app.use(express.json());

// Health check endpoint
app.get('/health', (req: Request, res: Response) => {
  res.status(200).json({ status: 'healthy' });
});

// MCP endpoint
app.post('/mcp', (req: Request, res: Response) => {
  try {
    const mcpRequest = req.body as MCPRequest;
    console.log('Received MCP request:', JSON.stringify(mcpRequest, null, 2));

    // Process the request based on the query
    const response = processQuery(mcpRequest);
    
    res.status(200).json({
      status: 'success',
      response
    } as MCPResponse);
  } catch (error) {
    console.error('Error processing MCP request:', error);
    res.status(500).json({
      status: 'error',
      error: error instanceof Error ? error.message : 'Unknown error',
      response: 'Sorry, there was an error processing your request.'
    } as MCPResponse);
  }
});

// Function to process different query types
function processQuery(request: MCPRequest): string {
  const { query, parameters } = request;

  // Example query handling - customize this for your use case
  switch (query) {
    case 'getCurrentTime':
      return `The current time is ${new Date().toLocaleTimeString()}`;
    
    case 'getWeather':
      const location = parameters?.location || 'Unknown';
      // In a real app, you would call a weather API here
      return `The weather in ${location} is currently sunny and 72°F`;
    
    case 'calculateSum':
      if (parameters?.numbers && Array.isArray(parameters.numbers)) {
        const sum = parameters.numbers.reduce((a: number, b: number) => a + b, 0);
        return `The sum of the numbers is ${sum}`;
      }
      return 'Invalid parameters for sum calculation';

    default:
      return `Unrecognized query: ${query}`;
  }
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`MCP server running on port ${PORT}`);
});

Ejecución de su servidor MCP

Para ejecutar su servidor, ejecute:

npx ts-node server.ts

Su servidor MCP ahora debería estar ejecutándose en el puerto 3000 (o el puerto especificado).

Conexión a Claude Desktop

Ahora que su servidor MCP está en funcionamiento, debe configurar Claude Desktop para que se conecte a él. Así es cómo:

Abra la aplicación Claude Desktop
Vaya a Configuración (generalmente en la esquina superior derecha)
Navegue a la sección "Funciones experimentales"
Habilite el interruptor "Protocolo de contexto del modelo"
Agregue un nuevo punto final MCP con la URL http://localhost:3000/mcp
Guarde su configuración

Claude Desktop ahora podrá comunicarse con su servidor MCP personalizado.

Prueba de la integración

Para probar su servidor MCP con Claude, intente hacerle a Claude preguntas que desencadenen las consultas específicas que ha implementado. Por ejemplo:

"¿Qué hora es ahora mismo?" (debería activar la consulta getCurrentTime)
"¿Qué tiempo hace en San Francisco?" (debería activar la consulta getWeather con "San Francisco" como parámetro de ubicación)
"¿Puedes calcular la suma de 5, 10, 15 y 20?" (debería activar la consulta calculateSum)

Cuando Claude reconoce que necesita información externa para responder a estas preguntas, enviará automáticamente una solicitud MCP a su servidor e incorporará la respuesta a su respuesta.

Extensión de su servidor MCP

El servidor básico que hemos construido es solo un punto de partida. Aquí hay algunas ideas para extender su funcionalidad:

Agregar autenticación

Para proteger su servidor MCP, agregue autenticación:

// Middleware for basic auth
const authenticateMCP = (req: Request, res: Response, next: Function) => {
  const apiKey = req.headers['x-api-key'];
  if (!apiKey || apiKey !== process.env.MCP_API_KEY) {
    return res.status(401).json({
      status: 'error',
      error: 'Unauthorized',
      response: 'Authentication failed'
    });
  }
  next();
};

// Apply middleware to MCP endpoint
app.post('/mcp', authenticateMCP, (req: Request, res: Response) => {
  // Existing handler code
});

Implementar la integración de la base de datos

Conecte su servidor MCP a una base de datos para recuperar o almacenar información:

import { MongoClient } from 'mongodb';

// Initialize database connection
const dbClient = new MongoClient('mongodb://localhost:27017');
let db: any;

async function connectToDb() {
  await dbClient.connect();
  db = dbClient.db('mcpDatabase');
  console.log('Connected to database');
}

connectToDb().catch(console.error);

// Add a query handler for database interactions
case 'getUserData':
  if (parameters?.userId) {
    const user = await db.collection('users').findOne({ id: parameters.userId });
    return user ? JSON.stringify(user) : 'User not found';
  }
  return 'Invalid user ID';

Agregar soporte de Webhook

Implemente la funcionalidad de webhook para notificar a los servicios externos:

case 'sendNotification':
  if (parameters?.message && parameters?.destination) {
    // Call external notification service
    await fetch('https://your-webhook-url.com', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: parameters.message })
    });
    return `Notification sent to ${parameters.destination}`;
  }
  return 'Invalid notification parameters';

Mejores prácticas para el desarrollo de servidores MCP

Maneje los errores con elegancia: Siempre capture las excepciones y devuelva mensajes de error informativos
Implemente el registro: Registre todas las solicitudes y respuestas para la depuración y la auditoría
Use interfaces TypeScript: Defina interfaces claras para todas las estructuras de datos
Establezca tiempos de espera: Implemente tiempos de espera de solicitud para evitar operaciones colgantes
Valide las entradas: Valide cuidadosamente todos los parámetros de entrada antes de procesarlos
Agregue pruebas unitarias: Pruebe a fondo sus controladores de consultas para garantizar la confiabilidad

Conclusión

La creación de un servidor TypeScript MCP abre posibilidades interesantes para extender las capacidades de Claude. Siguiendo esta guía, ha creado una base para integrar Claude con sus propios servicios y datos. El Protocolo de Contexto del Modelo permite una experiencia de usuario perfecta donde Claude puede acceder a información externa sin interrumpir el flujo de la conversación.

A medida que MCP continúa evolucionando, podemos esperar integraciones aún más sofisticadas entre los grandes modelos de lenguaje y los sistemas externos. Ya sea que esté creando herramientas de productividad, sistemas de gestión del conocimiento o aplicaciones comerciales personalizadas, MCP proporciona una forma poderosa de combinar la inteligencia de Claude con su funcionalidad especializada.

Comience a explorar las posibilidades extendiendo su servidor con controladores de consultas adicionales específicos para sus casos de uso y comparta sus experiencias con la creciente comunidad de desarrolladores de MCP.