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, qué puedes consultar a través de él, 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. El intercambio no tiene pantalla de consentimiento a propósito: como el servidor solo sirve documentación pública, no hay nada a lo que conceder acceso.
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.
El servidor indexa el contenido publicado en api-docs.kushkipagos.com para los cinco países: la referencia de la API (endpoints, parámetros, campos obligatorios, schemas, códigos de error y ejemplos de solicitud y respuesta) y las guías de integración de nuestras librerías y SDK. No incluye datos de tu cuenta, transacciones ni nada que esté detrás de un inicio de sesión.Tu asistente ve dos herramientas en el servidor:
Herramienta
Qué hace
apidocs___Retrieve
Busca en la documentación y devuelve los fragmentos más relevantes para una pregunta, cada uno con un puntaje de relevancia. Es la herramienta que tu asistente usa para responder tus prompts.
x_amz_bedrock_agentcore_search
Permite al asistente descubrir qué herramientas ofrece el servidor. Se usa internamente durante la conexión y no necesitas invocarla.
No invocas estas herramientas tú mismo: escribes una pregunta en el chat y el asistente decide cuándo usarlas. Como referencia, este es un ejemplo abreviado de lo que devuelve apidocs___Retrieve para la pregunta "Kushki Perú campos obligatorios para crear un cargo con tarjeta":
{"retrievalResults":[{"content":{"text":"...**Applies in Peru 🇵🇪.** ... 1. Obtain a card token by sending `initialRecurrence` in the `transactionMode` parameter. 2. Use the obtained token in step 1 to make an initial charge ...","type":"TEXT"},"score":0.5495},{"content":{"text":"\"initialRecurrenceReference\": { \"description\": \"Send here the `transactionReference` number obtained in the charge request of your initial recurrence charge without CVV...\", \"type\": \"string\" } ...","type":"TEXT"},"score":0.4670}]}
El asistente lee esos fragmentos y redacta la respuesta en el idioma que uses en el chat.
Menciona siempre el país
La búsqueda cubre la documentación de los cinco mercados a la vez. Si tu prompt no menciona un país, los resultados pueden mezclar fragmentos de distintos países, y el asistente puede combinar campos o flujos que no aplican a tu mercado. Incluye el país en cada prompt, por ejemplo "Kushki Perú" o "Kushki México".
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.Los nombres de los menús de cada herramienta cambian de una versión a otra. Si un paso no coincide con lo que ves en pantalla, la documentación oficial enlazada en cada pestaña tiene los pasos vigentes.
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.Sigue estos pasos:
1.
Abre la sección de conectores de la configuración de Claude.
2.
Elige la opción para agregar un conector personalizado.
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 organizaciones Team y Enterprise, un propietario agrega el conector desde la configuración de la organización, y después cada miembro lo habilita desde su propia página de conectores. La cantidad de conectores personalizados disponibles depende de tu plan de Claude; consulta la guía oficial de conectores personalizados para el detalle vigente.
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, comprueba primero que el servidor esté sano y después revisa los puntos siguientes.
Ejecuta el siguiente comando en tu terminal, o abre la dirección en tu navegador:
La respuesta esperada es status: ok con la lista de herramientas. Significa que el servidor hizo una consulta real a su backend y la documentación está disponible, así que cualquier problema que quede está en tu configuración local:
Si la respuesta trae otro status, o el comando devuelve un error, el problema está de nuestro lado y no en tu configuración. Espera unos minutos y vuelve a intentar; nuestro equipo recibe una alerta automática cuando el servidor está caído.
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.
Si el servidor aparece como conectado pero todas las preguntas fallan, devuelven un error o vuelven vacías, ejecuta la comprobación de salud descrita arriba. Un status distinto de ok confirma que el que falla es el servidor. Si la comprobación está bien, elimina el servidor de tu asistente, agrégalo de nuevo y repite la autorización.
Si la comprobación de salud devuelve un timeout o un error de red en lugar de una respuesta, tu red está bloqueando la conexión. Revisa las reglas de salida de tu red y asegúrate de que el tráfico HTTPS hacia apidocs-mcp.kushki-docs.workers.dev esté permitido.
Una vez conectado el servidor MCP, tu asistente de IA trabaja con la especificación real de nuestra API. Menciona siempre el país en tus prompts: la búsqueda cubre los cinco mercados y, sin país, el asistente puede mezclar campos o flujos de distintos países. Estos son algunos prompts que puedes usar como punto de partida:Explora la API"Consulta la documentación de Kushki México por MCP y lista los endpoints disponibles para pagos con tarjeta."Genera código de integración"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."Crea modelos de datos"Lee el schema del endpoint de cargos de Kushki Colombia y genera las interfaces de TypeScript para la solicitud y la respuesta."Entiende los flujos de pago"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."Maneja errores"Lista los códigos de error documentados para el endpoint de reembolso de Kushki Ecuador y sugiere cómo manejarlos en mi aplicación."Compara países"Compara los campos obligatorios para crear un cargo con tarjeta en Kushki México y en Kushki Perú, y dime las diferencias."Actualiza una integración existente"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.
