Servidor MCP (Model Context Protocol)

El servidor MCP de Salescaling permite que agentes de IA como Claude, Cursor y otros clientes compatibles con el protocolo MCP accedan a tus datos de reuniones, transcripciones y resúmenes de forma estructurada y segura.

¿Qué es MCP?

Model Context Protocol (MCP) es un protocolo estándar que permite a los modelos de lenguaje (LLMs) interactuar con sistemas externos de forma estructurada. El servidor MCP de Salescaling implementa este protocolo para exponer tus datos de reuniones a través de herramientas que los agentes de IA pueden usar.

Características

• ✅ Spec-Compliant: Implementación completa del protocolo MCP oficial

• ✅ 6 Herramientas Disponibles: Búsqueda, listado, transcripciones, resúmenes, datos completos y búsqueda por participante

• ✅ Búsqueda Avanzada: Full Text Search con PostgreSQL para búsquedas semánticas con índices GIN optimizados

• ✅ Control de Payload: Límites configurables para evitar overflow de contexto

• ✅ Autenticación Segura: Usa tu API key existente de Salescaling

• ✅ Multi-tenant: Aislamiento automático por organización

• ✅ Alto Rendimiento: Optimizado para millones de filas con índices GIN y control de concurrencia

Endpoints MCP

El servidor MCP expone dos endpoints principales:

GET /api/v1/mcp - Listar Herramientas

Retorna la lista de herramientas disponibles con sus esquemas de entrada.

Ejemplo:

curl -X GET https://api.salescaling.com/api/v1/mcp \
  -H "X-API-Key: sk_xxx"

POST /api/v1/mcp - Ejecutar Herramienta

Ejecuta una herramienta específica con los argumentos proporcionados.

Ejemplo:

curl -X POST https://api.salescaling.com/api/v1/mcp \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_meetings",
    "arguments": {
      "query": "performance",
      "limit": 10
    }
  }'

Herramientas Disponibles

1. search_meetings - Búsqueda Avanzada

Busca reuniones por texto en títulos y/o transcripciones usando PostgreSQL Full Text Search.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
query	string	Sí	Término de búsqueda
scope	string	No	title, sentences o all (default: all)
fromDate	string	No	Fecha inicio (YYYY-MM-DD)
toDate	string	No	Fecha fin (YYYY-MM-DD)
limit	number	No	Máximo 50 (default: 20)

Ejemplo:

{
  "name": "search_meetings",
  "arguments": {
    "query": "performance review",
    "scope": "all",
    "fromDate": "2024-12-01",
    "limit": 10
  }
}

2. list_meetings - Listar Reuniones

Lista reuniones con filtros estructurados.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
keyword	string	No	Búsqueda en nombres
fromDate	string	No	Fecha inicio
toDate	string	No	Fecha fin
limit	number	No	Máximo 50 (default: 20)
skip	number	No	Paginación (default: 0)
participants	string[]	No	Emails de participantes
organizers	string[]	No	Emails de organizadores

Ejemplo:

{
  "name": "list_meetings",
  "arguments": {
    "fromDate": "2024-12-01",
    "toDate": "2024-12-31",
    "participants": ["[email protected]"],
    "limit": 20
  }
}

3. get_meeting_transcript - Obtener Transcripción

Obtiene la transcripción detallada de una reunión con atribución de speakers.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
transcriptId	string	Sí	ID de la reunión
language	string	No	Código de idioma (ej: "es", "en")
maxSentences	number	No	Límite de oraciones (control de payload)

Control de Payload:

• Auto-trunca en 10,000 oraciones si no se especifica maxSentences

• Indica en la respuesta si se truncó el contenido

Ejemplo:

{
  "name": "get_meeting_transcript",
  "arguments": {
    "transcriptId": "meeting-uuid-here",
    "language": "es",
    "maxSentences": 100
  }
}

4. get_meeting_summary - Obtener Resumen

Obtiene el resumen de una reunión generado por IA.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
transcriptId	string	Sí	ID de la reunión
language	string	No	Código de idioma

Ejemplo:

{
  "name": "get_meeting_summary",
  "arguments": {
    "transcriptId": "meeting-uuid-here",
    "language": "es"
  }
}

5. get_meeting_details - Detalles Completos

Obtiene detalles completos de una reunión (metadatos + transcripción + resumen).

Parámetros:

Parámetro	Tipo	Requerido	Descripción
id	string	Sí	ID de la reunión
includeTranscript	boolean	No	Incluir transcripción (default: true)
includeSummary	boolean	No	Incluir resumen (default: true)
maxSentences	number	No	Límite de oraciones en transcript

Ejemplo:

{
  "name": "get_meeting_details",
  "arguments": {
    "id": "meeting-uuid-here",
    "includeTranscript": true,
    "includeSummary": true,
    "maxSentences": 500
  }
}

6. find_meetings_by_participant - Buscar Reuniones por Participante

Encuentra reuniones donde participó una persona específica. Busca por nombre (coincidencia parcial) o email (coincidencia exacta).

Parámetros:

Parámetro	Tipo	Requerido	Descripción
participant	string	Sí	Nombre o email del participante
fromDate	string	No	Fecha inicio (YYYY-MM-DD)
toDate	string	No	Fecha fin (YYYY-MM-DD)
limit	number	No	Máximo 50 (default: 20)
skip	number	No	Paginación (default: 0)

Características:

• Búsqueda por email: Coincidencia exacta (case-insensitive)

  • Ejemplo: [email protected] encontrará solo ese email exacto

• Búsqueda por nombre: Coincidencia parcial

  • Ejemplo: Jon encontrará "Jon Smith", "Jonathan", "Jon Doe", etc.

• Retorna información completa de participantes y organizador

• Ordenado por fecha descendente (más recientes primero)

Ejemplos:

Buscar por email:

{
  "name": "find_meetings_by_participant",
  "arguments": {
    "participant": "[email protected]",
    "fromDate": "2024-12-01",
    "limit": 20
  }
}

Buscar por nombre:

{
  "name": "find_meetings_by_participant",
  "arguments": {
    "participant": "Jon",
    "fromDate": "2024-01-01",
    "toDate": "2024-12-31",
    "limit": 50
  }
}

Configuración en Clientes MCP

Claude Desktop

1. Localiza tu archivo de configuración:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Agrega la configuración del servidor MCP:

{
  "mcpServers": {
    "salescaling": {
      "url": "https://api.salescaling.com/api/v1/mcp",
      "headers": {
        "X-API-Key": "sk_tu_api_key_aqui"
      }
    }
  }
}

1. Reinicia Claude Desktop

2. Verifica que el servidor esté conectado:

   • Busca el ícono de herramientas en la interfaz

   • Deberías ver "salescaling" como servidor disponible

   • Las 6 herramientas deberían aparecer listadas

Cursor IDE

1. Abre la configuración de Cursor (Cmd/Ctrl + ,)

2. Busca "MCP Servers" en la configuración

3. Agrega el servidor de Salescaling:

{
  "mcp.servers": {
    "salescaling": {
      "url": "https://api.salescaling.com/api/v1/mcp",
      "headers": {
        "X-API-Key": "sk_tu_api_key_aqui"
      }
    }
  }
}

1. Reinicia Cursor

2. Usa el servidor desde el chat de Cursor:

   • Menciona "@salescaling" en el chat

   • O pide directamente: "Busca reuniones sobre performance"

Otros Clientes MCP

Para cualquier cliente compatible con MCP:

1. URL del servidor: https://api.salescaling.com/api/v1/mcp

2. Autenticación: Header X-API-Key con tu API key

3. Protocolo: HTTP/HTTPS estándar

4. Formato: JSON

Ejemplos de Uso

Ejemplo 1: Buscar Reuniones con Claude

Usuario: "Busca reuniones sobre pricing del último mes"

Claude → POST /api/v1/mcp
{
  "name": "search_meetings",
  "arguments": {
    "query": "pricing",
    "scope": "all",
    "fromDate": "2024-12-01",
    "limit": 20
  }
}

Claude: "Encontré 5 reuniones sobre pricing:
1. Reunión de pricing con Acme Corp - 15 dic 2024
2. Review de estrategia de precios - 10 dic 2024
..."

Ejemplo 2: Obtener Transcripción Completa

Usuario: "Dame la transcripción completa de la reunión con ID abc-123"

Claude → POST /api/v1/mcp
{
  "name": "get_transcript",
  "arguments": {
    "transcriptId": "abc-123",
    "language": "es"
  }
}

Claude: "Aquí está la transcripción de la reunión:
[00:00 - 00:15] Juan Pérez: Buenos días a todos..."

Ejemplo 3: Análisis de Múltiples Reuniones

Usuario: "Analiza las reuniones de ventas de diciembre y dame insights"

Claude:
1. Lista reuniones → list_meetings (diciembre)
2. Para cada reunión → get_summary
3. Analiza patrones y genera insights

Claude: "He analizado 15 reuniones de diciembre:
- Temas más discutidos: pricing (8), implementación (6)
- Objeciones comunes: tiempo de implementación (5)
- Oportunidades identificadas: 3 cuentas enterprise..."

Formato de Respuesta

Todas las herramientas retornan respuestas en formato MCP estándar:

{
  "content": [
    {
      "type": "text",
      "text": "Descripción legible del resultado"
    },
    {
      "type": "resource",
      "resource": {
        "uri": "salescaling://meeting/xxx",
        "mimeType": "application/json",
        "text": "{...datos JSON estructurados...}"
      }
    }
  ]
}

Seguridad y Privacidad

Autenticación

• Todas las peticiones requieren una API key válida

• Las API keys se gestionan desde Configuración > API Keys

• Cada key está vinculada a tu organización (tenant)

Aislamiento de Datos

• El servidor MCP respeta el aislamiento multi-tenant

• Solo puedes acceder a reuniones de tu organización

• Los permisos de OpenFGA se aplican automáticamente

Mejores Prácticas

1. Nunca compartas tu API key: Trátala como una contraseña

2. Usa variables de entorno: No hardcodees la key en archivos

3. Rota las keys periódicamente: Crea nuevas keys y elimina las antiguas

4. Establece fechas de expiración: Para keys temporales o de prueba

5. Monitorea el uso: Revisa los logs de acceso regularmente

Límites y Cuotas

Rate Limiting

El servidor MCP comparte los mismos límites de la API pública:

• Corto plazo: 35 peticiones por segundo

• Mediano plazo: 200 peticiones cada 10 segundos

• Largo plazo: 1000 peticiones por minuto

Límites de Payload

• Transcripciones: Auto-trunca en 10,000 oraciones

• Búsquedas: Máximo 50 resultados por petición

• Listados: Máximo 50 reuniones por petición

Usa el parámetro maxSentences para controlar el tamaño de las transcripciones.

Troubleshooting

Error: "Unauthorized - missing or invalid API key"

Causa: API key no válida o no proporcionada

Solución:

1. Verifica que el header X-API-Key esté presente

2. Confirma que la key sea válida en Configuración > API Keys

3. Verifica que la key no haya expirado

Error: "Unknown tool: xxx"

Causa: Nombre de herramienta incorrecto

Solución:

1. Verifica el nombre de la herramienta (case-sensitive)

2. Usa GET /api/v1/mcp para ver las herramientas disponibles

3. Nombres válidos: search_meetings, list_meetings, get_transcript, get_summary, fetch

Error: "Meeting not found"

Causa: ID de reunión no existe o no tienes acceso

Solución:

1. Verifica que el ID sea correcto

2. Confirma que la reunión pertenezca a tu organización

3. Usa list_meetings para obtener IDs válidos

El servidor no aparece en Claude Desktop

Solución:

1. Verifica que el archivo de configuración esté en la ubicación correcta

2. Revisa que el JSON sea válido (sin errores de sintaxis)

3. Reinicia Claude Desktop completamente

4. Revisa los logs de Claude Desktop para errores

Respuestas muy largas o timeouts

Solución:

1. Usa maxSentences para limitar transcripciones

2. Reduce el limit en búsquedas y listados

3. Usa includeTranscript: false si solo necesitas el resumen

4. Filtra por fechas para reducir el conjunto de datos

Soporte

¿Necesitas ayuda con el servidor MCP?

• Email: [email protected]

• Documentación API: https://api.salescaling.com/api/docs

• Slack de la comunidad: Únete aquí

Recursos Adicionales

• Especificación MCP Oficial

• API Pública de Salescaling

• Gestión de API Keys

• Webhooks

---

Última actualización: Febrero 2026