Construí un MCP para mi instancia de Zendesk

Primero, qué es un MCP sin que suene a jerga

MCP significa Model Context Protocol. La idea es simple: es un puente que le permite a un asistente de IA hablar con una herramienta que ya usas.

Sin ese puente, Claude puede explicarte cómo funciona Zendesk, pero no puede mirar tu cuenta. Con el puente, le preguntas «¿cuántos tickets urgentes están sin asignar?» y va, consulta, y te responde con tu número real.

No es magia ni un modelo entrenado con tus datos. Es una conexión. Tu información sigue en Zendesk y el asistente solo pregunta lo que tú le pides que pregunte, con tus mismos permisos. Eso es todo lo que necesitas entender para usarlo.

Después, la decisión que más importó: hacerlo pequeño

Esta es la parte que quiero que te lleves aunque no instales nada. Estuve tentado a envolver toda la API de Zendesk, pero son cientos de endpoints. Podría haber hecho un servidor con doscientas herramientas y presumir de algo más complejo, pero ¿para qué? No era mi objetivo. ¿Puedo hacerlo? Sí, pero no es lo que buscaba aquí.

Además, cuando un asistente tiene doscientas herramientas disponibles, elige peor. Se satura, duda, y termina usando la equivocada o pidiéndote que le aclares lo que ya le dijiste. Menos opciones bien pensadas funcionan mejor que muchas opciones.

Entonces, en vez de preguntarme «¿qué puede hacer la API?», me pregunté «¿qué me quita tiempo a mí los lunes?». De ahí salieron cuatro áreas, y de esas cuatro áreas salieron trece herramientas.

Luego, investigar antes de escribir una sola línea

Lo segundo que hice fue aburrido pero decisivo: leer la documentación de la API de Zendesk antes de programar, no durante. Y como ya llevo años desarrollando con Zendesk, fue más fácil porque conocía la API. Aburrido sí, pero no complicado.

Te lo comento para que evites caer en errores como estos:

• La paginación. Zendesk tiene dos formas de paginar resultados. La tradicional tiene un techo de diez mil registros. Si tu cuenta tiene más tickets que eso, la auditoría te habría mentido sin avisar.
• Los límites de peticiones. Zendesk corta cuando pides demasiado por minuto y te dice cuántos segundos esperar. Si no lo respetas, el servidor se cae justo cuando más lo estás usando.
• Los tokens de API están deprecados. La propia documentación de Zendesk indica que un token de API permite suplantar a cualquier miembro de la cuenta, administradores incluidos, y recomienda usar OAuth. Para uso personal el token sirve, pero esa advertencia cambió cómo diseñé la seguridad.

En paralelo, la seguridad: tres capas y ninguna opcional

Esto no lo dejé para el final, y creo que es lo que diferencia un juguete de algo que te atreves a conectar a tu cuenta real.

• Tus mismos permisos. El servidor nunca puede hacer más de lo que ese usuario ya podía hacer entrando a la interfaz. Si quieres un servidor de solo lectura, le das el token de un usuario con permisos de lectura y listo.
• Casi todo es de solo lectura. De las trece herramientas, once solo leen. Las dos que modifican cosas (reasignar tickets, suspender o cambiar el rol de un usuario) fallan con un mensaje claro hasta que las habilitas a propósito.
• Primero un ensayo. Aun habiéndolas habilitado, esas dos primero te dicen qué cambiarían sin tocar nada. Tienes que pedirlo otra vez para que se ejecute de verdad.

Me parece la decisión más importante del proyecto. Un asistente de IA con permisos de escritura sobre tu Zendesk y sin frenos es una idea pésima, por bien que funcione el noventa y nueve por ciento de las veces.

Y antes de darlo por bueno, probarlo de tres formas

• Pruebas sin conexión. Corren sin credenciales, simulando las respuestas de Zendesk. Verifican que la autenticación se arme bien, que la paginación recorra todas las páginas, que ante un corte por límite de peticiones espere lo que debe, y que el candado de las escrituras funcione en los dos sentidos.
• Arranque real. Una prueba que levanta el servidor de verdad y confirma que las trece herramientas se registran correctamente.
• Prueba contra tu Zendesk. Un script que llama a tu cuenta real y te dice, uno por uno, qué endpoints responden con tu token. Es más útil de lo que parece: te avisa de entrada si tu plan no incluye algo, en vez de que lo descubras cuando una herramienta falle.

Ahora la parte chévere: lo que puedes hacer con él

Trece herramientas, en cinco grupos. En lenguaje normal:

Buscar tickets

• Por número de ticket, por correo del cliente, por asunto, o por el teléfono del contacto.
• Los tres últimos se combinan: «tickets de ana@empresa.com sobre facturación».

Limpiar la configuración

• Qué triggers y macros no se han ejecutado en un mes.
• Cuáles están encendidos pero no hacen nada.
• Cuáles están duplicados o llevan meses sin tocarse.
• Qué campos de ticket no usa nadie.

Saber cómo va la operación

• Cuántos tickets están abiertos, por estado y por prioridad.
• Cuántos no tienen dueño y cuáles llevan demasiado tiempo quietos.
• Quién del equipo está cargando más.
• Qué políticas de SLA tienes y con qué objetivos.

Revisar la seguridad

• Quién tiene permisos de administrador.
• Qué tokens de acceso llevan meses sin usarse y qué aplicaciones están instaladas.
• Qué cambió en la configuración la semana pasada y quién lo cambió (solo en plan Enterprise).

Cuando alguien se va del equipo

• Qué quedó pendiente en su cola, a qué grupos pertenece y cuándo entró por última vez.
• Pasar sus tickets a otra persona.
• Suspender su acceso.

Y una cosa que no esperaba que fuera tan útil: todo lo anterior se pregunta en lenguaje normal. No hay comandos que memorizar. Escribes «audita mis triggers buscando reglas muertas» y ya.

Cómo lo instalas

Necesitas tres cosas: tu computador, Python 3.10 o superior, y permisos de administrador en Zendesk.

1. Descarga el proyecto

git clone https://github.com/Grjhoan/Zendesk_MCP_Server
cd Zendesk_MCP_Server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Crea tu token en Zendesk

En tu cuenta: Admin Center → Apps and integrations → APIs → Zendesk API → Settings. Habilita Token access y crea un token nuevo. Cópialo en ese momento, porque Zendesk no te lo vuelve a mostrar.

Recuerda que esta forma está siendo retirada, así que te conviene cambiar a OAuth. Yo usé el token para testear rápido, pero no es lo recomendado.

3. Configúralo

cp .env.example .env

Abre el .env y llena tres campos: tu subdominio, tu correo y el token.

Ojo con el subdominio: va solo el nombre. Si entras por https://miempresa.zendesk.com, el valor es miempresa. Nada más.

4. Comprueba que funciona antes de conectar nada

python check_connection.py

Esto te dice con qué cuenta y rol quedaste conectado, y prueba uno por uno los endpoints que usa cada herramienta. Si algo no está disponible en tu plan, lo sabes aquí y no cuando falle.

Cómo lo conectas a Claude

Hay dos caminos. Puedes usar los dos a la vez.

Si usas Claude Code

Un comando y listo:

claude mcp add zendesk-admin \
  -- /ruta/absoluta/.venv/bin/python /ruta/absoluta/server.py

Usa rutas absolutas, y reinicia Claude Code después, porque las herramientas se registran al arrancar.

Si usas la aplicación de Claude

Aquí se instala como extensión. Primero la empaquetas:

./build_mcpb.sh

Eso deja una carpeta dist/ lista. Después, en la app: Settings → Extensions → Advanced settings → Install unpacked extension, y seleccionas esa carpeta dist/.

Dos advertencias que aprendí a golpes:

• Señala la carpeta dist/, no la del proyecto. Solo dist/ tiene lo que la app necesita.
• Después de instalar, ve a Settings → Connectors, entra a Zendesk Admin y llena ahí el subdominio, el correo y el token. Cada vez que reinstales la extensión, esa configuración se borra y hay que volver a ponerla.

Pruébalo

Abre una conversación nueva y escribe algo como:

Si te responde con tu cuenta y tu rol, ya está. Un detalle: no escribas los nombres de las herramientas como si fueran comandos. Describe la tarea en palabras normales y el asistente elige la herramienta.

Lo que todavía no hace, y lo que deberías saber antes

• Corre en tu computador, no en la nube. Eso es bueno para la seguridad: tu token se queda en tu máquina y nada queda expuesto a internet. Pero significa que no puedes consultarlo desde el celular.
• El registro de auditoría es solo para plan Enterprise. La herramienta de cambios recientes de configuración te lo dirá con claridad si tu plan no lo incluye.
• El teléfono es del contacto, no del ticket. Si en tu operación guardas los números en un campo personalizado del ticket en vez de en la ficha del usuario, esa búsqueda no encontrará nada. ¿Se puede hacer? Sí, pero no lo incluí en esta versión. Escríbeme si te interesa desarrollar más cosas como esta.
• Los tokens de API están deprecados. Funcionan, y para una herramienta personal son suficientes. Pero si esto crece a varias personas, muévete a OAuth. El servidor ya acepta los dos, y OAuth es la opción recomendada.

Si quieres usarlo

El repositorio está aquí: github.com/Grjhoan/Zendesk_MCP_Server.

Es software libre, con licencia MIT. Úsalo, cámbialo, llévatelo como base para construir lo tuyo. Si tu stack no es Zendesk sino Freshdesk, Intercom o lo que sea, el método es el mismo: identifica primero qué quieres resolver, revisa la documentación de su API antes de escribir nada, y pon los frenos de seguridad desde el primer día.