Conecta tu aplicación con tus agentes Sidemex.

1. Conecta tu cuenta

1. Inicia sesión en el dashboard de Sidemex. Haz clic en tu avatar o correo, abajo a la izquierda; también puedes usar clic derecho o el teclado.
2. Elige Conectores MCP → Asistentes virtuales. En Sidemex AI también encontrarás el botón Conectores MCP.
3. Selecciona Claude, ChatGPT, Gemini o Kimi. Para otra aplicación, pulsa Crear conexión MCP. Esto prepara el acceso de Sidemex; la conexión se termina en un cliente compatible con MCP por HTTP y autenticación Bearer.
4. Escribe un nombre para reconocer la conexión, marca sus permisos y elige 1 día, 7 días o 30 días. Pulsa Crear acceso.
5. Copia la Dirección del servidor MCP y pulsa Copiar token. El token se muestra una sola vez. Guárdalo como secreto y no lo incluyas en código público ni en JavaScript del navegador. Copiar configuración JSON ofrece una referencia para clientes que admitan ese formato.
6. En tu cliente MCP, añade un servidor HTTP con esa dirección y el encabezado Authorization: Bearer TU_TOKEN. Comprueba las herramientas disponibles. Cada cliente tiene sus propios ajustes; algunas aplicaciones o planes no admiten servidores MCP personalizados.

Abrir Conectores MCP →

Para crear y publicar desde el SDK, selecciona agents:write y agents:publish. Si solo consultarás agentes, usa workspace:read. Los accesos vencen en 1, 7 o 30 días. Recibirás un aviso por correo 6 horas antes para accesos de 1 día y 24 horas antes para los de 7 o 30 días.

En Accesos de tu cuenta puedes revisar nombre, permisos, vencimiento y último uso. Para renovar, crea un nuevo acceso y reemplaza el token en tu cliente. Después pulsa Revocar en el anterior y confirma: su acceso se interrumpe de inmediato.

El token determina qué cuenta y herramientas puede usar tu integración. No necesitas enviar tu correo ni un identificador de cuenta en cada operación.

Guía del dashboard: crea y administra tu agente

Abre Agentes desde la navegación o el menú de tu cuenta. Puedes crear el agente aquí o mediante un asistente conectado por MCP; ambos aparecen en la misma lista.

De «Nuevo agente» a tu primera prueba

1. Nueva recepcionista IA / Nuevo agente. Ambos abren la configuración guiada. En el primer paso escribe Nombre del agente, Nombre del negocio y el objetivo. Elige el Tipo de agente que necesitas.
2. Datos del negocio. Busca tu ficha de Google Maps y revisa nombre y dirección antes de seleccionarla. Si tienes sitio web, escribe su dirección y pulsa Leer; revisa los datos encontrados. Si no tienes sitio, marca la opción correspondiente y completa el contexto manualmente. Pulsa Continuar.
3. ¿Qué tipo de negocio va a atender? Selecciona la tarjeta que corresponda al giro de tu negocio. Si se sugirió una automáticamente, verifica que sea correcta. Pulsa Continuar.
4. Lo que tu recepcionista debe saber. Completa o corrige la descripción, servicios y precios publicados, horario, teléfono, correo, WhatsApp, dirección e información adicional. Usa datos reales y explica qué debe hacer si desconoce una respuesta. Pulsa Aprobar y seguir cuando hayas revisado la información.
5. ¿Cómo contesta tu recepcionista? Elige su voz y escribe el saludo que escucharán tus clientes. Selecciona las funciones que necesita: resolver dudas, agendar citas, tomar recados o pasar a una persona. Pulsa Crear recepcionista o Crear agente. Si alcanzaste el límite de tu plan, revisa Uso y límites antes de crear otro.
6. ¿Cómo llegan las llamadas? Elige un número virtual de Sidemex, desvío, tu proveedor SIP o Lo hago después. La opción de Sidemex permite elegir entre los números disponibles de tu cuenta. Si necesitas otro, abre el marketplace en una pestaña nueva y vuelve para seleccionarlo. Para tu proveedor SIP, abre el Conmutador y completa la conexión. Pulsa el botón de conexión o Continuar según tu elección.
7. Probar a tu agente. Al terminar, abre la prueba. Revisa su comportamiento, contexto, voz y número; guarda el borrador antes de probar. Realiza una conversación con las preguntas que harán tus clientes y revisa el resultado en Llamadas.

Crear mi agente →

Abre, cambia y activa tu agente

Integraciones y menú de tu cuenta

En Sidemex AI, pulsa Integraciones para abrir tus conexiones. En el popup, la pestaña Integraciones reúne telefonía, voces, mensajería y otras conexiones: elige un proveedor, sigue sus instrucciones, completa los campos y pulsa Conectar. Revisa el estado de verificación. Quitar revoca esa conexión. La pestaña Asistentes virtuales permite crear y administrar accesos MCP.

Tu avatar o correo abre Conectores MCP, Agentes, Uso y límites, Ajustes y Cerrar sesión. Uso y límites muestra tu plan y créditos; Ajustes abre la configuración de tu cuenta.

2. Instala el SDK TypeScript

Ejecuta este comando en tu proyecto Node.js. Instala @sidemex/mcp-sdk versión 1.0.2 desde la descarga oficial.

npm install https://sidemex.net/docs/agents/downloads/sidemex-mcp-sdk-1.0.2.tgz

Descargar SDK 1.0.2

Configura SIDEMEX_MCP_TOKEN en el entorno de tu aplicación con el token del paso anterior. Luego inicializa el cliente y consulta las herramientas disponibles:

import { SidemexMcpClient } from '@sidemex/mcp-sdk';

const token = process.env.SIDEMEX_MCP_TOKEN;
if (!token) throw new Error('Configura tu token de acceso MCP.');

const client = new SidemexMcpClient({
  token,
  clientInfo: { name: 'mi-integracion', version: '1.0.0' },
});

try {
  const connection = await client.initialize();
  const tools = await client.listTools();
  console.log(connection.name, tools.map(tool => tool.name));

  const inventory = await client.agents({ limit: 20 });
  console.log(inventory.agents);
} finally {
  await client.close();
}

El cliente ya incluye el endpoint de Sidemex. listTools() devuelve las herramientas autorizadas para tu acceso. close() cierra la conexión; para abrir otra, crea un cliente nuevo.

3. Crea, guarda y publica tu agente

Crea un borrador

Con el cliente inicializado y el permiso agents:write, crea una recepcionista usando inbound_receptionist. Para un agente de llamadas salientes, usa outbound_caller.

import { createRequestId } from '@sidemex/mcp-sdk';

// Guarda este identificador y sus argumentos en tu aplicación antes de enviarlos.
const input = {
  kind: 'inbound_receptionist' as const,
  name: 'Ana · Recepción',
  requestId: createRequestId(),
};

const created = await client.createAgent(input);
const agentId = created.result.agent.id;
const workspace = await client.workspace(agentId);
console.log({ agentId, revision: workspace.revision, state: workspace.agent.state });

Crear un agente devuelve su id y lo deja como borrador. Guarda ese identificador para las siguientes operaciones.

Configura, publica y activa

Lee la configuración actual con workspace() y el esquema disponible con schema(). Completa el contexto del negocio, la voz y, para recepción telefónica, el número de tu cuenta y una ruta de respaldo. Puedes hacerlo desde el dashboard o guardar los campos con el SDK.

import { createRequestId } from '@sidemex/mcp-sdk';

// agentId identifica un agente de tu cuenta.
const current = await client.workspace(agentId);
if (!current.config) throw new Error('Completa la configuración del agente.');
const config = structuredClone(current.config);

config.shared.behavior.greeting = 'Hola, soy Ana, la asistente virtual. ¿En qué puedo ayudarte?';
config.shared.behavior.goal = 'Responder consultas y tomar solicitudes de cita.';

// Guarda cada requestId y sus argumentos antes de enviar la operación.
const saveInput = { agentId, revision: current.revision, config, requestId: createRequestId() };
const saved = await client.saveDraft(saveInput);

// Completa primero el perfil aprobado, la voz y la telefonía en el dashboard.
const publishInput = { agentId, revision: saved.result.revision, requestId: createRequestId() };
const published = await client.publishAgent(publishInput);

const activateInput = { agentId, versionId: published.result.versionId, requestId: createRequestId() };
await client.activateAgent(activateInput);

const active = await client.workspace(agentId);
console.log({ state: active.agent.state, activeVersionId: active.activeVersionId });

saveDraft() necesita la revisión actual. publishAgent() crea una versión de esa revisión y activateAgent() activa la versión elegida. Los dos últimos métodos requieren agents:publish y una configuración válida.

Para detener un agente, usa client.pauseAgent({ agentId, requestId: createRequestId() }). Consulta después workspace() para comprobar el estado.

Configura lo que tu agente debe hacer

El SDK usa VoiceConfig con schema_version: 2. Consulta client.schema() para obtener los campos y valores admitidos. Lee y conserva la configuración actual antes de modificarla.

El nombre del agente se define al crearlo. El nombre, ofertas, horarios y datos de contacto del negocio se preparan en su perfil.

Prepara el contexto de tu negocio

buildProfile() prepara un perfil con el sitio web y los datos que indiques. Revisa las fuentes y los campos pendientes antes de aprobarlo. Si no tienes sitio web, usa websiteUrl: null y completa los datos manuales.

import { createRequestId } from '@sidemex/mcp-sdk';

const prepared = await client.buildProfile({
  websiteUrl: 'https://tu-negocio.example',
  manual: {
    business_name: 'Mi negocio',
    one_liner: 'Servicios de mantenimiento para hogares y oficinas.',
    offers: [{ name: 'Mantenimiento', description: 'Servicio con cita previa',
      price_text: 'Cotización personalizada', unit: '' }],
    service_area: 'León, Guanajuato',
    booking: { method: 'phone', url: '' },
    call_goal: 'Resolver dudas y tomar solicitudes de cita.',
  },
  locale: 'es',
  requestId: createRequestId(),
});

const profile = prepared.result.profile;
console.log({ data: profile.data, gaps: profile.gaps, sources: profile.sources });

// Revisa y completa los datos antes de aprobar esta versión.
await client.approveProfile({ version: profile.version, requestId: createRequestId() });
// Asigna profile.version a shared.context.business_profile_version del borrador.

Preparar el perfil requiere agents:write; aprobarlo requiere agents:publish. Después de aprobar, guarda su versión en el contexto del agente y publica la nueva configuración.

Encuentra tu negocio en Google Places

Busca por nombre y ciudad, revisa la dirección y consulta los detalles de la ficha correcta. Necesitas agents:write, un plan con prospección habilitada y créditos disponibles.

const results = await client.searchPlaces({
  query: 'Nombre del negocio, León Guanajuato',
  locale: 'es',
  requestId: createRequestId(),
});
console.log(results.result.places, results.result.creditsUsed);

// Usa el id de la ficha correcta después de revisar nombre y dirección.
const details = await client.readPlace({
  placeId: selectedPlaceId,
  locale: 'es',
  requestId: createRequestId(),
});
console.log(details.result.place, details.result.creditsUsed);

Las respuestas incluyen creditsUsed y la atribución Google Maps. Verifica los datos antes de usarlos en tu perfil y conserva esa atribución al mostrarlos. La preparación del perfil y las consultas de Places pueden consumir créditos.

Conecta otro cliente MCP

Si tu asistente o aplicación admite MCP con Streamable HTTP, configura la siguiente URL y envía el token como cabecera Bearer:

https://sidemex.app/api/medusa/ai/agents/sdmx/mcp
Authorization: Bearer <TU_TOKEN>

La conexión utiliza JSON-RPC 2.0 y la versión de protocolo 2025-11-25. Inicializa la sesión, guarda la cabecera Mcp-Session-Id y envía notifications/initialized antes de consultar herramientas.

# Ejemplo Bash. SIDEMEX_MCP_TOKEN contiene el token de tu cuenta.
ENDPOINT='https://sidemex.app/api/medusa/ai/agents/sdmx/mcp'

curl --fail-with-body -sS -D mcp-headers.txt "$ENDPOINT" \
  -H "Authorization: Bearer $SIDEMEX_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"mi-integracion","version":"1.0.0"}}}'

# Copia Mcp-Session-Id de mcp-headers.txt a SESSION.
SESSION='ID_DE_SESION_RECIBIDO'

curl --fail-with-body -sS "$ENDPOINT" \
  -H "Authorization: Bearer $SIDEMEX_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H "Mcp-Session-Id: $SESSION" \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl --fail-with-body -sS "$ENDPOINT" \
  -H "Authorization: Bearer $SIDEMEX_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H "Mcp-Session-Id: $SESSION" \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Para ejecutar una herramienta, envía tools/call con name y arguments según su inputSchema en tools/list. Incluye el Bearer, Mcp-Session-Id, MCP-Protocol-Version y los tipos aceptados en cada solicitud.

En PowerShell, usa curl.exe y adapta las variables y comillas, o usa el SDK. Revisa el cuerpo de la respuesta: un HTTP 200 también puede contener un error JSON-RPC o una herramienta con isError: true.

Planes y consumo

Los permisos MCP no cambian la capacidad de tu plan. El número de agentes, las funciones habilitadas y el saldo disponible se comprueban igual que en el dashboard.

1,000 créditos Sidemex equivalen a USD 1 de saldo de consumo, antes de impuestos. Voz, Sidemex AI y las operaciones que utilizan API comparten la bolsa de tu cuenta. Consulta el consumo registrado y las funciones disponibles antes de automatizar operaciones.

La recarga automática se utiliza únicamente cuando la activas. Si faltan créditos o espacios para agentes, la operación devuelve el bloqueo correspondiente.

Usa también Sidemex AI y WhatsApp

Desde Sidemex AI puedes pedir que prepare una recepcionista con el sitio y la información de tu negocio y guarde el borrador. Continúa la publicación desde el dashboard o con un acceso MCP que tenga agents:publish.

Para usar el chat de tu cuenta por WhatsApp, vincula y verifica tu número desde el dashboard. La conexión de chat no concede por sí sola permiso para publicar agentes.

Si quieres que tu agente envíe mensajes durante una llamada, habilita la conexión de mensajería y las acciones disponibles para tu cuenta. Añadir un enlace de WhatsApp o un menú al contexto permite conocerlo; el envío requiere una conexión activa.

Prueba tu integración antes de activarla

En el sitio de Sidemex puedes escuchar una vista previa de 1:30 minutos sin cuenta. Al elegir Ventas o Asistente personal, la llamada web se prepara automáticamente; permite el micrófono para conversar. Al terminar, crea tu cuenta o inicia sesión para retomar el contexto con tus créditos disponibles. En Recepción de negocios también encontrarás Llamar, que muestra el número público sin pedir acceso.

1. Comprueba que initialize() y listTools() funcionan con tu acceso.
2. Crea un borrador y verifica que aparece en Agentes en tu dashboard.
3. Guarda un saludo y un objetivo; vuelve a leer workspace() para comprobar los cambios y la revisión.
4. Revisa el perfil del negocio, la voz, las acciones y la telefonía desde el dashboard.
5. Publica y activa cuando la configuración esté completa. Comprueba el estado y prueba la conversación desde el agente.

Conserva los identificadores de operación para resolver resultados inciertos sin duplicar cambios. Si necesitas ayuda para conectar una demostración pública, contacta a soporte.

Resuelve errores y reintentos

Las operaciones que modifican agentes o preparan información requieren un requestId de 32 caracteres hexadecimales. Genera uno por operación con createRequestId() y guarda sus argumentos antes de enviarla. Una repetición debe usar el mismo identificador y los mismos argumentos.

El SDK no reintenta automáticamente estas operaciones. Si un corte de conexión deja el resultado incierto, consulta operation() y el agente antes de volver a actuar.

import { SidemexMcpError } from '@sidemex/mcp-sdk';

// persistedSaveInput conserva el requestId y los argumentos originales.
try {
  await client.saveDraft(persistedSaveInput);
} catch (error) {
  if (error instanceof SidemexMcpError) {
    console.error({ code: error.code, toolCode: error.toolCode,
      httpStatus: error.httpStatus, outcomeUnknown: error.outcomeUnknown });

    if (error.outcomeUnknown) {
      const receipt = await client.operation({
        operation: 'save', requestId: persistedSaveInput.requestId,
      });
      console.log(receipt.state, receipt.result);
    }
  }
  throw error;
}

Cada método admite { signal, timeoutMs } para cancelación y tiempo de espera. Cancelar una solicitud después de enviarla no confirma que el cambio se haya detenido. Guarda errores y recibos sin registrar tu token.

Recursos de conexión

Comparte esta guía con quien configure tu integración. Estos recursos describen el acceso público de Sidemex:

• llms.txt: presentación y enlaces de Sidemex para asistentes de IA.
• Manifiesto MCP: endpoint y datos de conexión.
• Documentación general: primeros pasos con tu cuenta.

Para usar herramientas de tu cuenta necesitas tu propio acceso. El catálogo disponible se obtiene con listTools() después de conectar.