TeeckIn/Documentación

Resolución de problemas

Problemas habituales y soluciones para la integración de agentes de IA.

Problemas de autenticación

Error «invalid_client»

Posibles causas:

  • -El Client ID o el Client Secret se copiaron mal
  • -El Client Secret se ha revocado
  • -El agente se ha desactivado

Soluciones:

  • +Verifica que TEECKIN_CLIENT_ID empieza por «teeckin_agent_»
  • +Verifica que TEECKIN_CLIENT_SECRET empieza por «tcs_»
  • +Comprueba el estado del secreto en Configuración > Agentes > pestaña Secretos
  • +Crea un nuevo secreto si el actual se ha revocado

Error «Access token expired»

Posibles causas:

  • -Los tokens de acceso son válidos durante 1 hora
  • -El token no se renovó antes de caducar

Soluciones:

  • +Solicita un nuevo token de acceso usando tus credenciales de cliente
  • +El servidor MCP se encarga de esto automáticamente
  • +Para el uso de la API, solicita un nuevo token en /api/oauth/token

Error «Agent not found»

Posibles causas:

  • -Uso de credenciales de un agente eliminado
  • -El agente nunca se creó correctamente

Soluciones:

  • +Crea un nuevo agente y guarda las credenciales
  • +Asegúrate de copiar tanto el Client ID como el Client Secret cuando se muestren

Problemas del cronómetro

El cronómetro no se inicia

Posibles causas:

  • -Ya hay otro cronómetro en marcha
  • -ID de tema no válido
  • -Límite de uso superado

Soluciones:

  • +Comprueba el estado con teeckin_get_status o GET /api/timer/active
  • +Para el cronómetro existente antes de iniciar uno nuevo
  • +Usa teeckin_list_topics para obtener IDs de tema válidos

El cronómetro se detuvo de forma inesperada

Posibles causas:

  • -Alguien lo paró manualmente en la interfaz
  • -Reinicio del servidor (poco frecuente)
  • -El agente se desactivó a mitad de sesión

Soluciones:

  • +Revisa tus entradas de tiempo para ver si quedó registrado
  • +Inicia un nuevo cronómetro si es necesario

La entrada de tiempo no aparece

Posibles causas:

  • -El cronómetro sigue en marcha (no se detuvo)
  • -Estás mirando un rango de fechas incorrecto
  • -Estás viendo el espacio de trabajo personal en lugar de la organización

Soluciones:

  • +Para el cronómetro para crear la entrada
  • +Comprueba el calendario en la fecha correcta
  • +Cambia al contexto de organización correcto

Problemas con los temas

Error «Topic not found»

Posibles causas:

  • -Uso de un ID de tema que no existe
  • -El tema se ha eliminado
  • -El tema está en otra organización

Soluciones:

  • +Actualiza tu lista de temas con teeckin_list_topics
  • +Usa la lista de temas actualizada para obtener IDs válidos

La coincidencia aproximada elige el tema equivocado

Posibles causas:

  • -Varios temas tienen nombres parecidos
  • -La consulta es demasiado ambigua

Soluciones:

  • +Usa nombres de tema más específicos
  • +Usa el ID completo del tema en lugar del nombre
  • +Incluye el nombre de la categoría: «Backend API Development»

Problemas del servidor MCP (Claude Code)

El servidor MCP no se conecta

Posibles causas:

  • -JSON no válido en .mcp.json o .claude/settings.json
  • -Variables de entorno sin definir (TEECKIN_CLIENT_ID, TEECKIN_CLIENT_SECRET)
  • -Problemas de conectividad de red
  • -Un cortafuegos bloquea las conexiones HTTPS

Soluciones:

  • +Valida la sintaxis de tu JSON con un validador de JSON
  • +Verifica que las variables de entorno estén exportadas en el perfil de tu shell
  • +Prueba la conectividad de red: curl https://api.teeckin.com/mcp
  • +Comprueba que tu red permita conexiones HTTPS salientes (puerto 443)

Prueba la conexión

Verifica que tus credenciales funcionan con curl:

bash
# First get an access token
curl -X POST https://api.teeckin.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$TEECKIN_CLIENT_ID" \
  -d "client_secret=$TEECKIN_CLIENT_SECRET"

# Then test the MCP endpoint
curl -X POST https://api.teeckin.com/mcp \
  -H "Authorization: Bearer tat_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude no ve las herramientas de TeeckIn

Posibles causas:

  • -La URL del servidor MCP no está configurada en .mcp.json
  • -Claude Code necesita reiniciarse tras cambiar la configuración
  • -Las credenciales de OAuth no están configuradas en la sección env

Soluciones:

  • +Verifica que mcpServers.teeckin.url esté establecido en https://api.teeckin.com/mcp
  • +Reinicia Claude Code tras editar los archivos de configuración
  • +Comprueba que la sección env incluya TEECKIN_CLIENT_ID y TEECKIN_CLIENT_SECRET

Problemas del servidor MCP (Codex)

El servidor MCP no se conecta

Posibles causas:

  • -TOML no válido en ~/.codex/config.toml
  • -Falta la sección [mcp_servers.teeckin]
  • -TEECKIN_CLIENT_ID o TEECKIN_CLIENT_SECRET no están exportados en el shell

Soluciones:

  • +Revisa la sintaxis de TOML: las secciones necesitan [corchetes] y las cadenas "comillas"
  • +Ejecuta npx @teeckin/agent init --codex para regenerar la configuración
  • +Asegúrate de que tanto TEECKIN_CLIENT_ID como TEECKIN_CLIENT_SECRET estén exportados en el perfil de tu shell

Codex no ve las herramientas de TeeckIn

Posibles causas:

  • -La configuración no está en ~/.codex/config.toml (a nivel de usuario)
  • -Codex necesita reiniciarse tras cambiar la configuración
  • -A env_vars le faltan las credenciales de OAuth

Soluciones:

  • +La configuración MCP debe estar en ~/.codex/config.toml, no a nivel de proyecto
  • +Reinicia Codex tras editar config.toml
  • +Verifica que [mcp_servers.teeckin] incluya env_vars = ["TEECKIN_CLIENT_ID", "TEECKIN_CLIENT_SECRET"]

Los hooks no se disparan

Posibles causas:

  • -hooks.json no está en el directorio .codex/
  • -La función de hooks no está habilitada en config.toml
  • -Sintaxis JSON no válida en hooks.json

Soluciones:

  • +Asegúrate de que .codex/hooks.json exista en la raíz de tu proyecto
  • +Añade [features] codex_hooks = true a config.toml si es necesario
  • +Valida la sintaxis de hooks.json con un validador de JSON

Límites de uso

Error «Rate limit exceeded» (429)

Posibles causas:

  • -Demasiadas llamadas a la API en poco tiempo
  • -Script o bucle descontrolado
  • -Varias integraciones que comparten las mismas credenciales

Soluciones:

  • +Espera 60 segundos y reinténtalo
  • +Implementa un retroceso exponencial en tu integración
  • +Usa agentes o secretos distintos para integraciones distintas
  • +Almacena en caché la lista de temas en lugar de pedirla repetidamente

Límites de uso

  • Solicitudes GET: 120 por minuto
  • Solicitudes POST/PATCH: 30 por minuto
  • Operaciones del cronómetro: 10 por minuto

Problemas de permisos

«Permiso denegado» al acceder a la configuración de agentes

Posibles causas:

  • -No estás en el contexto de organización
  • -Intento de acceder a los agentes de otro miembro
  • -El rol en la organización no permite el acceso

Soluciones:

  • +Cambia a la organización correcta
  • +Solo puedes gestionar tus propios agentes (salvo que seas administrador)
  • +Pide ayuda a un administrador con la configuración de agentes a nivel de organización

El agente no puede acceder a la facturación/tarifas

Posibles causas:

  • -Es el comportamiento esperado: los agentes tienen permisos restringidos

Soluciones:

  • +Los agentes no pueden ver, de forma intencionada, las tarifas por hora ni los datos de facturación
  • +Es una función de seguridad, no un error

Problemas con los agentes personales

La pestaña «Agentes» no aparece en Configuración

Posibles causas:

  • -Actualmente estás viendo un contexto de organización
  • -Los agentes personales requieren el espacio de trabajo personal

Soluciones:

  • +Cambia al espacio de trabajo personal (haz clic en tu nombre en la barra lateral y selecciona «Personal»)
  • +Los agentes personales solo son visibles en la Configuración personal, no en las organizaciones

Error «Pro subscription required»

Posibles causas:

  • -El plan gratuito no incluye agentes personales
  • -Los agentes personales requieren Pro o superior

Soluciones:

  • +Actualiza a la suscripción Pro para acceder a los agentes personales
  • +Si usas una organización, esta necesita el plan Team para los agentes de organización

El agente personal registra en los temas equivocados

Posibles causas:

  • -El agente accede a temas de organización cuando se esperaban temas personales
  • -El agente se creó en el contexto equivocado

Soluciones:

  • +Los agentes personales solo acceden a los temas personales
  • +Los agentes de organización solo acceden a los temas de esa organización
  • +Crea un nuevo agente en el contexto correcto si es necesario

Obtener ayuda

Si sigues teniendo problemas:

  • 1.Comprueba que tus credenciales sean válidas y que el agente esté activo
  • 2.Prueba la API directamente con curl para aislar el problema
  • 3.Revisa los registros de Claude Code en busca de errores específicos de MCP
  • 4.Contacta con soporte con tu mensaje de error y los pasos para reproducirlo