Construyamos un servidor MCP de TypeScript y conectémonos a Claude Desktop

Los modelos de lenguaje grandes (LLM, por sus siglas en inglés) como Claude de Anthropic son cada vez más capaces, pero para desbloquear completamente su potencial, necesitan acceso a un contexto externo enriquecido. Aquí es donde entra en juego el Protocolo de Contexto del Modelo (MCP): una forma estandarizada para que las herramientas, aplicaciones y servicios comuniquen el contexto a los LLM. En este artículo, te guiaremos a través de la creación de un servidor MCP en TypeScript, exploraremos cómo interactúa con los clientes y demostraremos cómo conectarlo a Claude Desktop.

💡

Antes de entrar en detalles, echa un vistazo a Apidog: una herramienta potente para diseñar, probar y documentar API. Apidog te permite integrar tus API sin problemas, mejorando tu flujo de trabajo con modelos estructurados y una fácil colaboración. Si buscas impulsar tu automatización y gestión de API.

button

¿Qué es el Protocolo de Contexto del Modelo (MCP)?

El Protocolo de Contexto del Modelo es un protocolo universal que define cómo las aplicaciones LLM (hosts), los servidores y los clientes intercambian datos. MCP permite la integración modular basada en herramientas con fuentes de datos locales o en línea de una manera escalable y estructurada. Es especialmente útil en entornos LLM basados en escritorio, como Claude Desktop o Sourcegraph Cody.

A un alto nivel, el protocolo incluye:

Hosts: La aplicación basada en LLM (p. ej., Claude Desktop)
Clientes: Módulos integrados que gestionan las conexiones a los servidores
Servidores: Proveedores de herramientas, datos o servicios
Transports: El mecanismo subyacente para enviar y recibir mensajes JSON-RPC

¿Por qué usar MCP?

Los métodos tradicionales como copiar y pegar o codificar el contexto son torpes y limitados. MCP resuelve estos problemas al permitir:

Descubrimiento de herramientas y negociación de capacidades
Intercambio de mensajes basado en JSON-RPC
Una interfaz consistente en todos los lenguajes y plataformas
Separación limpia entre la aplicación LLM y las herramientas externas

Esta modularidad permite a los desarrolladores crear herramientas potentes con reconocimiento de contexto que pueden interactuar con los LLM en tiempo real.

Requisitos previos

Para crear un servidor TypeScript MCP y conectarlo a Claude Desktop, necesitarás:

Node.js (v18+)
TypeScript
Conocimientos básicos de JSON-RPC

Claude Desktop

MCP TypeScript SDK

Paso 1: Configurar tu proyecto

Comienza configurando un proyecto Node.js:

mkdir mcp-ts-server
cd mcp-ts-server
npm init -y
npm install typescript ts-node @modelcontextprotocol/server-core
npx tsc --init

Crea un directorio src/ y, dentro de él, añade tu archivo de punto de entrada, p. ej., index.ts.

Paso 2: Crear tu servidor MCP en TypeScript

Vamos a crear un servidor MCP simple que proporcione una "herramienta" para saludar a los usuarios.

Aquí está la estructura básica:

import { createServer, Server } from '@modelcontextprotocol/server-core';

const server: Server = createServer();

const GREETING_TOOL = {
  name: 'greet_user',
  description: 'Returns a friendly greeting message.',
  inputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Name of the user' }
    },
    required: ['name']
  }
};

// Register tool
server.setRequestHandler('ListTools', async () => {
  return { tools: [GREETING_TOOL] };
});

// Handle tool call
server.setRequestHandler('CallTool', async (request) => {
  const args = request.args;
  const name = args.name || 'there';
  return {
    content: [{ type: 'text', text: `Hello, ${name}! Welcome to MCP.` }],
    isError: false
  };
});

// Start server
server.listen();

Ahora puedes compilar y ejecutar esto con:

npx ts-node src/index.ts

Paso 3: Registrar tu servidor con Claude Desktop

Cada servidor MCP necesita un URI único. Por ejemplo:

tool://greet_user/greet_user

Cuando Claude Desktop se inicializa, puede descubrir el servidor a través de un transporte Stdio. Esto significa que tu servidor se comunica a través de la entrada/salida estándar (stdin/stdout) en lugar de HTTP o sockets.

Paso 4: Conectar el servidor MCP a Claude Desktop

En Claude Desktop:

Ve a Settings > Tool Providers
Añade un nuevo proveedor de herramientas utilizando un transporte Stdio
Especifica tu URI de herramienta y el comando para ejecutar tu servidor, p. ej.:

npx ts-node src/index.ts

Claude Desktop iniciará la comunicación utilizando JSON-RPC 2.0 a través de stdin/stdout, y tu servidor deberá responder con la lista de herramientas que admite.

¡Por supuesto! Aquí tienes una versión reescrita de la sección de configuración de Claude Desktop que puedes insertar directamente en tu artículo:

Usar Claude Desktop para probar tu servidor MCP

La aplicación Claude Desktop es uno de los entornos más fáciles para probar las integraciones de MCP localmente.

Para configurarlo manualmente para que inicie tu servidor MCP, sigue estos pasos:

Abre o crea el archivo en:

~/Library/Application Support/Claude/claude_desktop_config.json

noconfig.json

Añade la siguiente configuración JSON, reemplazando los detalles según sea necesario para tu herramienta:

{
  "mcpServers": {
    "brave_search": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}

Esto le dice a Claude Desktop que:

Reconozca una herramienta llamada brave_search
La inicie a través de npx @modelcontextprotocol/server-brave-search
Inyecte variables de entorno, como tu clave API
Guarda el archivo y reinicia Claude Desktop.

Una vez reiniciado, puedes pedirle a Claude Desktop que use tu nueva herramienta. Por ejemplo:

"Busca en la web glama.ai"

Si es la primera vez que usas MCP, Claude te pedirá permiso a través de un cuadro de diálogo emergente. Haz clic en "Permitir para este chat" para continuar.

Después de eso, Claude activará tu servidor MCP y transmitirá los resultados directamente en la conversación.

Mejora tu automatización de IA con la integración del servidor Apidog MCP
Lleva tus flujos de trabajo impulsados por IA aún más lejos integrándote con el Servidor Apidog MCP.

Esta potente conexión permite a tu asistente de IA interactuar directamente con las especificaciones de la API de los proyectos de Apidog, lo que permite una exploración perfecta de la API, la generación de código y la creación de modelos estructurados.

Ya sea que estés creando una herramienta de saludo simple o integrando servicios avanzados como la búsqueda web, crear tu propio servidor MCP en TypeScript te da control total sobre cómo Claude accede y procesa el contexto externo, desbloqueando experiencias de IA más inteligentes e interactivas.

Descripción general del flujo de mensajes

Esto es lo que sucede internamente:

1. Inicialización

Claude (como host) envía una solicitud de inicialización con la versión y las capacidades del protocolo admitidas.

2. Negociación de capacidades

Tu servidor responde con sus propias capacidades, y el cliente confirma la preparación con una notificación de inicializado.

3. Descubrimiento de herramientas

Claude envía una solicitud ListTools. Tu servidor devuelve una lista de definiciones de herramientas, incluidos los esquemas de entrada.

4. Llamada a la herramienta

Cuando el usuario activa la herramienta (p. ej., escribiendo "saluda a Juan"), Claude envía una solicitud CallTool con argumentos.

Tu servidor la procesa y devuelve un mensaje de resultado con el contenido de la respuesta.

Paso 5: Ampliar tu ecosistema de herramientas

Una vez que tu servidor esté funcionando, puedes ampliar sus capacidades:

Búsqueda web: Integrar la API de Brave Search
Sistema de archivos: Lecturas/escrituras de archivos seguras
Herramientas de Slack o GitHub: Habilitar funciones de colaboración
Google Drive: Archivos adjuntos y contexto de contenido

Por ejemplo, aquí hay un fragmento de una integración del servidor Brave Search:

const WEB_SEARCH_TOOL = {
  name: 'brave_web_search',
  description: 'Search the web using Brave.',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string' },
      count: { type: 'number', default: 10 }
    },
    required: ['query']
  }
};

Opciones de transporte

Si bien Stdio es mejor para las pruebas locales, MCP también admite:

HTTP + SSE: Bueno para aplicaciones web y servicios remotos
Transportes personalizados: Conecta tu propio adaptador de transporte

Todos usan JSON-RPC 2.0 para la codificación de mensajes.

Herramientas de depuración y prueba

Puedes probar tu servidor MCP con la herramienta de código abierto Inspector:

git clone https://github.com/modelcontextprotocol/inspector

Permite el rastreo de mensajes, la simulación de solicitudes y la depuración de los comportamientos de las herramientas.

Casos de uso del mundo real

Algunos de los primeros usuarios de MCP incluyen:

Sourcegraph Cody: Mejora el contexto de desarrollo
Zed Editor: Integraciones de IDE
Claude Desktop: Operaciones LLM locales y privadas

Estas herramientas demuestran el poder de MCP tanto en entornos fuera de línea como en línea, lo que facilita a los desarrolladores personalizar cómo la IA comprende su contexto.

Conclusión

MCP es un paso adelante poderoso para brindar estructura, escalabilidad y modularidad a la forma en que los LLM interactúan con las herramientas y los datos. Ya sea que estés creando un asistente personal, un ayudante de IDE o una canalización de datos, MCP ofrece un estándar a prueba de futuro para conectar capacidades externas.

Siguiendo esta guía, has aprendido cómo:

Crear un servidor MCP simple usando TypeScript
Registrarlo con Claude Desktop
Comprender cómo fluye la comunicación de la herramienta
Ampliar la funcionalidad utilizando API y servicios adicionales

Para los desarrolladores que crean la próxima generación de aplicaciones mejoradas con IA, dominar MCP es un paso esencial.

Lecturas y recursos adicionales

Guía de inicio rápido completa: Protocolo de contexto del modelo en Glama.ai
Repositorios de GitHub: Herramientas MCP