Conecta tu asistente de IA con la documentación oficial de la API de Kushki.Los asistentes de IA se han vuelto una herramienta clave para acelerar las integraciones de pagos. Por eso, en Kushki publicamos las especificaciones oficiales de nuestra API como un servidor MCP. Así, herramientas como Claude o Cursor leen directamente la documentación vigente de cada país, en lugar de depender de su conocimiento previo o de fragmentos que copias a mano.En esta guía aprenderás qué es MCP, cómo conectarlo a tu asistente de IA y cómo aprovecharlo en tu integración con Kushki.
Ten en cuenta
Este servidor solo expone nuestra documentación pública. No necesitas credenciales de Kushki ni una cuenta de Apidog para usarlo. La primera vez que se conecta, tu asistente completa un intercambio de autorización automático con el servidor: no hay formulario de inicio de sesión ni se te pide ningún dato. Algunos asistentes abren una pestaña del navegador por un momento, o muestran un botón Connect o Authenticate por única vez.
MCP (Model Context Protocol) es un protocolo abierto que conecta asistentes de IA con fuentes de datos externas. Funciona como un canal de comunicación estandarizado: el asistente consulta la información directamente en la fuente y devuelve respuestas basadas en lo que dice la documentación hoy.En Kushki publicamos un único servidor MCP remoto que cubre la documentación de nuestros cinco mercados: México, Perú, Colombia, Ecuador y Chile. El servidor lee las especificaciones oficiales publicadas en nuestro portal de documentación, lo que significa que la IA conoce nuestros endpoints, schemas y parámetros reales. Como resultado, genera código, modelos de datos y respuestas alineados con la versión vigente de la documentación.Esta es la dirección del servidor MCP de Kushki:
https://apidocs-mcp.kushki-docs.workers.dev/
El servidor usa el transporte Streamable HTTP, el estándar actual para servidores MCP remotos. Tu asistente se conecta directamente a esa URL, sin instalar nada.
Frecuencia de actualización
El servidor MCP se sincroniza con nuestro portal de documentación cada 24 horas. Si publicamos un cambio en la documentación, puede tardar hasta un día en reflejarse en las respuestas del servidor. Para actualizaciones muy recientes, revisa la documentación del país correspondiente en nuestro portal de documentación.
Antes de empezar, asegúrate de contar con lo siguiente:
Un asistente de IA compatible con MCP, como Claude, Claude Code, Cursor, VS Code o Cline.
La última versión de ese asistente. El soporte para servidores remotos viene incluido en las versiones actuales y mejora con cada lanzamiento.
Conexión a internet, ya que tu asistente consulta la documentación en tiempo real.
Un servidor MCP es una fuente de datos, no un asistente: no tiene interfaz propia. Conectarlo solo le da a tu asistente acceso a nuestra documentación, así que siempre lo consultas desde el chat de la herramienta que ya usas.
Busca tu herramienta en las pestañas de abajo y sigue sus pasos. Todas las rutas se conectan al mismo servidor y te dan la misma información, y solo necesitas configurarlo una vez: la URL se mantiene sincronizada con la documentación publicada, así que tu asistente accederá a la versión sincronizada más reciente sin ningún cambio en tu configuración.
Claude
Claude Code
Cursor
VS Code
Cline
Otros asistentes
En Claude, el servidor se agrega como un conector personalizado. Esto funciona tanto en Claude Desktop como en claude.ai, y no requiere que edites archivos ni instales nada.Follow these steps:
1.
Ve a Customize > Connectors. En algunas versiones de Claude Desktop, esta opción está en Settings > Connectors.
2.
Selecciona + y luego Add custom connector.
3.
En el campo Name, escribe Kushki APIs.
4.
En el campo de la URL, pega la dirección del servidor MCP de Kushki.
5.
Confirma con Add. Claude completa la autorización por su cuenta y el conector aparece en la lista como disponible.
6.
Abre un chat nuevo, despliega el menú de conectores y comprueba que Kushki APIs está habilitado.
En el plan Free puedes mantener un conector personalizado. Los planes Pro, Max, Team y Enterprise no tienen ese límite. En organizaciones Team y Enterprise, un propietario agrega el conector desde Organization settings > Connectors, y después cada miembro lo habilita desde su propia página de Connectors.
Si el archivo de configuración ya contiene otros servidores, agrega solo el bloque interno "kushki-apis": { ... }, separado del servidor anterior por una coma, y conserva el bloque de tu propia herramienta.
Importante
Mantén una sola clave principal en el archivo. Si la duplicas, el JSON quedará inválido y tu asistente ignorará toda la configuración.
Para confirmar que todo funciona, hazle a tu asistente una pregunta de prueba, por ejemplo: "Consulta la documentación de Kushki Perú por MCP y dime qué campos son obligatorios para crear un cargo con tarjeta." Si la respuesta devuelve información correcta sobre la API de Kushki, la conexión fue exitosa.Si tu asistente no responde con información de nuestra documentación, revisa los siguientes puntos.
Revisa que la clave principal aparezca solo una vez, que una coma separe cada bloque y que no falten comillas. Un archivo JSON inválido hace que el asistente ignore toda la configuración.Comprueba también que copiaste el bloque de la pestaña de tu propia herramienta. El nombre de la clave principal y el valor del campo type no son intercambiables entre asistentes.
El servidor aparece como pendiente de autorización#
Selecciona el servidor en el panel MCP de tu asistente y confirma la autorización. Es un intercambio automático que no te pide credenciales.Si conectaste el servidor con mcp-remote y deja de responder, elimina la carpeta ~/.mcp-auth y reinicia tu asistente para que repita el intercambio.
Ejecuta el siguiente comando en tu terminal para confirmar que el servidor responde:
La respuesta esperada es 401. Ese código confirma que el servidor está en línea y pidiendo la autorización que tu asistente completa por su cuenta, así que el problema está en tu configuración local. Si en cambio obtienes un timeout o un error de red, revisa las reglas de salida de tu red.
Una vez conectado el servidor MCP, tu asistente de IA trabaja con la especificación real de nuestra API. Menciona el país en tus prompts para que el asistente encuentre la documentación correcta. Estos son algunos prompts que puedes usar como punto de partida:Explore the API"Consulta la documentación de Kushki México por MCP y lista los endpoints disponibles para pagos con tarjeta."Generate integration code"Con base en la especificación de Kushki Perú, genera el código en Node.js para solicitar un token de tarjeta y luego crear un cargo único."Create data models"Lee el schema del endpoint de cargos de Kushki Colombia y genera las interfaces de TypeScript para la solicitud y la respuesta."Understand payment flows"Explica el flujo de autorización y captura en dos pasos según la documentación de Kushki Chile y genera un ejemplo en Python."Handle errors"Lista los códigos de error documentados para el endpoint de reembolso de Kushki Ecuador y sugiere cómo manejarlos en mi aplicación."Compare countries"Compara los campos obligatorios para crear un cargo con tarjeta en Kushki México y en Kushki Perú, y dime las diferencias."Update an existing integration"Compara mi implementación actual de cargo con tarjeta con la especificación vigente de Kushki y dime qué campos me faltan."
El asistente responde con base en nuestra documentación, pero no la reemplaza. Antes de salir a producción, valida los campos y flujos de tu integración contra la referencia del país correspondiente.
Con esta conexión, tu asistente deja de adivinar y empieza a construir sobre nuestra documentación oficial. Empieza a integrar la API de Kushki con la ayuda de la IA y reduce el tiempo de desarrollo de tu solución de pagos.
Kushki Developers
Explora nuestras soluciones de pago para cada mercado.
Model Context Protocol
Conoce cómo funciona el protocolo abierto detrás de esta integración.
