Cómo diseñar un MCP server para conectar tu CRM
MCP (Model Context Protocol) es el estándar abierto de Anthropic para conectar herramientas externas a Claude. Si usas Claude Code y tienes un CRM, un MCP server es el puente que los conecta. En vez de copiar datos del CRM, pegarlos en Claude, recibir una respuesta y volver al CRM a actualizarlo, un MCP server permite que Claude haga todo eso directamente.
Este tutorial es técnico: necesitas saber algo de JavaScript o TypeScript para implementarlo. Si no programas, puedes usarlo como brief para un desarrollador. Con este documento, un dev junior monta el server en 2-3 días.
Qué es MCP y cómo funciona
MCP define un protocolo de comunicación entre Claude y herramientas externas. Un MCP server expone 'tools' (funciones) que Claude puede llamar cuando las necesita. La comunicación se hace por stdio (entrada/salida estándar), lo que significa que el server se ejecuta como un proceso local en tu ordenador.
Cuando le dices a Claude 'Busca al cliente Acme Corp en el CRM', Claude detecta que tiene una tool llamada search_contacts disponible, la llama con el parámetro 'Acme Corp', el MCP server ejecuta la búsqueda en la API del CRM y devuelve los resultados a Claude, que los interpreta y te los presenta.
Todo esto pasa en milisegundos. Para ti, es como si Claude tuviera acceso nativo al CRM.
Elegir qué operaciones exponer
El error más común al diseñar un MCP server es exponer demasiadas operaciones. Si tu CRM tiene 100 endpoints de API, no necesitas exponer los 100 como tools. Claude trabaja mejor con un conjunto limitado de herramientas bien descritas que con una lista interminable.
Empieza con las 5 operaciones que más usas. Para la mayoría de equipos de ventas, estas son: buscar contactos (la más usada, con diferencia), ver detalle de un contacto o empresa (datos, historial, oportunidades asociadas), listar oportunidades (filtradas por estado, fecha, responsable), actualizar el estado de una oportunidad y registrar una actividad o nota.
Cada operación adicional añade complejidad. Cuando las primeras 5 funcionen bien, añade más según la necesidad real de tu equipo.
Arquitectura del server
Un MCP server tiene tres capas:
1. El protocolo MCP: lo maneja el SDK (@modelcontextprotocol/sdk). No necesitas implementar nada a este nivel.
2. Las tools: las funciones que defines con nombre, descripción, esquema de parámetros y lógica. Cada tool es un handler que recibe parámetros y devuelve un resultado.
3. El cliente de CRM: una capa que encapsula las llamadas HTTP a la API de tu CRM. Maneja autenticación, paginación, rate limiting y errores.
La separación en capas importa. Si mañana cambias de CRM (de Pipedrive a HubSpot), solo cambias la capa 3. Las tools y sus descripciones se mantienen.
Implementación paso a paso
Inicializa el proyecto:
mkdir crm-mcp-server cd crm-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod
El punto de entrada (src/index.ts) crea el servidor y registra las tools. Cada tool se registra con server.tool(), pasando el nombre, la descripción, el esquema de Zod para los parámetros y la función async que ejecuta la lógica.
Escribir descripciones que Claude entienda
Las descripciones de las tools son la parte más importante del diseño. No son documentación para humanos: son instrucciones para que Claude sepa cuándo usar cada tool.
Una mala descripción: 'Busca contactos.' Claude no sabe cuándo usar esto.
Una buena descripción: 'Busca contactos en el CRM de la empresa por nombre, empresa o email. Usa esta herramienta cuando el usuario pregunte por un cliente específico, quiera ver el historial de un contacto o necesite datos de una persona en la base de datos. Devuelve: nombre completo, empresa, email, teléfono, fecha del último contacto y número de oportunidades abiertas.'
La descripción debe responder tres preguntas: ¿qué hace?, ¿cuándo usarla? y ¿qué devuelve?
El cliente de CRM
El cliente de CRM es una clase de TypeScript que encapsula las llamadas HTTP. Usa fetch (nativo en Node 18+) o axios para las peticiones. Los puntos clave:
Autenticación: lee la API key de una variable de entorno. Nunca la hardcodees.
Rate limiting: la mayoría de APIs de CRM tienen límites (100-500 peticiones por minuto). Añade un delay entre llamadas o implementa un queue.
Paginación: si la búsqueda devuelve más de 100 resultados, necesitas paginar. Pero para un MCP server, raramente necesitas más de la primera página. Limita a 20-50 resultados por búsqueda.
Errores: convierte los errores de la API en mensajes legibles. Claude muestra estos mensajes al usuario, así que 'No se encontró ningún contacto con el nombre Acme' es mejor que 'HTTP 404: Not Found'.
Conectar a Claude Code
La configuración se hace en .claude/settings.json (a nivel de proyecto) o en ~/.claude/settings.json (global). Añade una entrada en mcpServers con: el nombre del server, el comando para ejecutarlo y las variables de entorno.
Ejemplo de configuración:
mcpServers: { 'crm': { command: 'node', args: ['dist/index.js'], cwd: '/ruta/a/crm-mcp-server', env: { CRM_API_KEY: 'tu-api-key' } } }
Reinicia Claude Code después de cambiar la configuración. Las tools del MCP server aparecen disponibles automáticamente.
Testing y debugging
Prueba cada tool de forma aislada antes de conectarla a Claude. Puedes usar el MCP Inspector (npx @modelcontextprotocol/inspector) para probar tu server sin Claude. El Inspector te permite llamar a cada tool manualmente y ver la respuesta.
Los errores más comunes: la variable de entorno no está configurada (el server arranca pero falla al llamar al CRM), el esquema de Zod no coincide con los parámetros que envía Claude (Claude envía 'query' pero tu esquema espera 'search_term') y el formato de respuesta no es texto plano (Claude espera texto, no JSON crudo).
Para debugging, añade console.error() en tus handlers. Los logs van a stderr y no interfieren con el protocolo MCP (que usa stdout).
Seguridad
Un MCP server que conecta con tu CRM tiene acceso a datos sensibles. Tres reglas:
1. Las tools de escritura (update, create, delete) deben tener confirmación. Antes de actualizar un deal o crear una nota, Claude debe pedir confirmación al usuario. Esto se configura en la descripción de la tool: 'Antes de ejecutar esta acción, confirma con el usuario los datos exactos que se van a escribir.'
2. Las credenciales van en variables de entorno, nunca en el código. Y el archivo .claude/settings.json con las credenciales no se sube a git (añádelo a .gitignore o usa .claude/settings.local.json).
3. Limita el alcance: si tu equipo de ventas solo necesita leer contactos y deals, no expongas tools para borrar registros. Menos superficie de ataque.
Evolución del server
Un MCP server crece con el uso. Empiezas con 5 tools básicas. Después de un mes, tu equipo te pide: 'Sería genial poder generar un reporte de pipeline directamente desde Claude.' Añades una tool generate_pipeline_report. 'Sería útil poder buscar en las notas de los contactos.' Añades search_notes.
Cada nueva tool es un archivo en la carpeta src/tools/. La estructura modular permite crecer sin complicar el código existente.
Coste y mantenimiento
El MCP server en sí es gratuito: se ejecuta localmente en tu ordenador. El coste es el tiempo de desarrollo (1-3 días para la primera versión) y el mantenimiento cuando la API del CRM cambia (raro, pero pasa). No consume tokens de Claude adicionales más allá de los que ya usas en tu sesión de Claude Code.
El ROI es inmediato para equipos que pasan mucho tiempo alternando entre Claude y su CRM. Si tu equipo de ventas usa Claude para redactar emails, preparar llamadas o analizar oportunidades, un MCP server les ahorra entre 30 minutos y 2 horas diarias de copiar datos entre ventanas.