Saltar al contenido principal

Conecte un agente de IA

Conecte un agente de IA a Kanera con OAuth interactivo, una conexión de servicio desatendida o una clave API. El método correcto depende de si el agente actúa como una persona, se ejecuta sin supervisión o solo admite credenciales estáticas.

Para ChatGPT o una superficie Codex compatible, instale el Kanera complemento y conecte su cuenta a través de su mensaje OAuth. Seguir Configurar ChatGPT o Configurar el códice; el complemento incluye la habilidad Kanera y la conexión MCP.

Para otros asistentes personales, utilice OAuth cuando su cliente admita MCP remoto con autenticación del navegador. Agrega la dirección MCP de Kanera, aprueba la conexión y el agente actúa como usted respetando su función en cada foro. Utilice una conexión desatendida para CI o automatización del lado del servidor, o una Clave de API cuando el cliente no soporta OAuth.

Configuración rápida para agentes de codificación​

Pegue esto en Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode u otro agente de codificación:

Fetch https://www.kanera.app/agent-setup/prompt.md and follow it.

El mensaje instala la habilidad de agente oficial de Kanera, registra el servidor MCP alojado utilizando la configuración del agente actual e inicia OAuth donde el cliente lo admite. Revise la pantalla de consentimiento del navegador antes de aprobar el acceso.

Elija un método de conexión​

Conexión¿Quién actúa comodonde lo configurasteLo mejor para
OAuth (interactivo)Usted, después de una pantalla de consentimiento del navegador. Sin clave API.Agrega la dirección MCP a su agente; Kanera maneja el inicio de sesión y el consentimiento. Gestionarlo en Configuración de perfil -> Claves API.Un asistente personal de IA en Claude, ChatGPT, Copilot o Codex.
OAuth (código de dispositivo)Tú, después de aprobar un código corto en un navegador. Sin clave API.El cliente muestra un código; lo apruebas en la Kanera Conectar un dispositivo página. Gestionarlo en Configuración de perfil -> Claves API.Una CLI, una sesión SSH o una máquina sin cabeza que no puede abrir una redirección del navegador.
Agente desatendido (conexión de servicio)Una identidad de servicio de espacio de trabajo, con ámbito de lectura, escritura o administrador.Configuración del espacio de trabajo -> API, "Agentes de IA desatendidos".CI, trabajos cron o un agente del lado del servidor sin ningún ser humano que pueda hacer clic en Permitir.
Clave de APIEl propietario de la clave (personal) o el espacio de trabajo (clave del espacio de trabajo).Configuración de perfil -> Claves API o Configuración del espacio de trabajo -> API.MCP estándar local o clientes que no admiten OAuth.

Requisitos​

  • Su cliente AI debe admitir servidores MCP remotos con OAuth. Los clientes que solo admiten un token de portador estático deben usar un Clave de API en cambio.
  • Las conexiones interactivas de agentes funcionan en todos los planes de Kanera, incluido el gratuito. En los foros de una organización Libre los agentes de cada persona comparten un límite de 5 solicitudes por segundo y 60 por minuto; los tableros Pro permiten 20 y 400. Ver Límites de tarifas.

¿Cómo sé si mi agente admite OAuth?​

No existe una lista fija y la atención al cliente cambia con el tiempo, por lo que la comprobación confiable es probarla:

  1. Agregue la dirección MCP de Kanera a su cliente como servidor MCP remoto o personalizado.
  2. Si el cliente admite OAuth, abre una pestaña del navegador Kanera para iniciar sesión y dar su consentimiento. Esa es tu confirmación.
  3. Si, en cambio, el cliente le solicita una clave API, un token o un Authorization encabezado, o simplemente no logra conectarse, no es compatible con OAuth. Utilice un Clave de API en cambio.

Los clientes que describen soporte para "servidores MCP remotos", "conectores personalizados" u "OAuth" generalmente funcionan. Para un cliente que solo ejecuta servidores stdio locales, apúntelo a kanera mcp desde el Kanera CLI después kanera auth login; transmite el servidor alojado con su inicio de sesión OAuth, por lo que aún no necesita una clave.

Conectar un agente (interactivo)​

  1. Abierto Configuración de perfil -> Claves API.

  2. en el Conexión de agente de IA sección, copie el dirección MCP. Para el servicio alojado de Kanera esto es:

    https://mcp.kanera.app/mcp

  3. Agregue esa dirección a su cliente AI como servidor MCP remoto. bajo O configurarlo a mano, elija Claude Code, Cursor, VS Code/GitHub Copilot, Codex o Gemini CLI para copiar un comando o configuración listos para usar con su dirección MCP ya completada. Para otros clientes, siga los propios pasos del cliente para agregar un conector MCP personalizado o remoto.

  4. El cliente abre una pestaña del navegador Kanera. Inicie sesión si aún no lo ha hecho y luego revise la pantalla de consentimiento.

  5. Elige Permitir acceso. Kanera te devuelve con el agente, que ahora está conectado.

No ingresa una clave API en ningún momento. El agente recibe un token de acceso de corta duración y lo actualiza automáticamente en segundo plano.

Configuración de API personal que muestra el mensaje de configuración del agente, la dirección MCP de Kanera, un comando de configuración de Claude Code copiable y administración del agente conectado.

OAuth conecta las herramientas; por sí solo no enseña al cliente flujos de trabajo específicos de Kanera. Si su cliente admite Agent Skills, instale también el Habilidad del agente Kanera:

npx -y skills add https://github.com/happendev/Kanera/tree/main/integrations/skills/kanera --yes --global

La habilidad guía al agente para leer el estado actual, resolver ID estables, realizar cambios solicitados de forma segura y manejar correctamente las fallas de autenticación o permisos. Consulte las guías de configuración específicas del cliente en esta sección para conocer las ubicaciones de las habilidades manuales.

La pantalla de consentimiento nombra al agente y explica los límites de la conexión. Un agente conectado de esta manera:

  • leer tableros, tarjetas, notas, comentarios y actividades a las que puede acceder.
  • Crear y actualizar contenido del tablero dondequiera que seas editor.
  • Crear y administrar espacios de trabajo donde sea que sea administrador: como administrador de una organización puede crear espacios de trabajo y tableros independientes, y como administrador del espacio de trabajo puede agregar tableros a ese espacio de trabajo y crear, editar, habilitar y eliminar sus automatizaciones. Otras tareas de administración, como la edición de listas, campos, etiquetas y miembros, permanecen en la interfaz de Kanera.

Kanera utiliza estos alcances de OAuth para agentes autorizados por el usuario:

AlcanceSubvenciones
kanera:readLea el contenido del tablero al que pueda acceder.
kanera:writeCrea y actualiza el contenido del tablero donde eres editor.
offline_accessAceptado cuando un cliente lo solicita. Kanera emite un token de actualización cada vez que el cliente se registra para la actualización, de modo que el agente pueda permanecer conectado sin pedirle que inicie sesión nuevamente.

Las conexiones interactivas y de código de dispositivo siempre reciben kanera:read y kanera:write, incluso cuando un cliente omite alcances o solicita solo lectura. Esto mantiene el servidor compatible con clientes que manejan los permisos de acción de manera diferente. El cliente de IA sigue siendo responsable de decidir a qué herramientas puede acceder el usuario y cuándo solicitar confirmación. Kanera verifica de forma independiente el rol actual del usuario conectado en cada solicitud, por lo que un observador no puede escribir en un tablero. En Kanera Cloud, el política de agente de IA de la organización También puede hacer que los agentes sean de solo lectura o desactivarlos para los tableros de una organización. offline_access sigue siendo opcional porque controla la actualización del token en lugar de los permisos de la herramienta Kanera.

Administrar y desconectar agentes​

Abierto Configuración de perfil -> Claves API y encontrar el Conexión de agente de IA sección.

  • Cada agente conectado muestra su nombre, sus alcances otorgados y cuándo se conectó.
  • Elige Agente de desconexión para revocar una conexión. Sus tokens de acceso y actualización dejan de funcionar inmediatamente, por lo que el agente pierde el acceso de inmediato.

Desconectarse es la forma más rápida de desconectar un cliente de IA que ya no utiliza o en el que no confía.

Agentes desatendidos (conexiones de servicio)​

OAuth interactivo necesita una persona para hacer clic Permitir. Para CI, trabajos cron o un agente personalizado del lado del servidor sin presencia humana, cree un agente desatendido en la configuración del espacio de trabajo. Se autentica con una identificación de cliente y un secreto utilizando OAuth. client_credentials subvención.

Si una persona está presente pero el cliente no puede abrir una redirección del navegador, como una CLI o una sesión SSH, use autorización del dispositivo en cambio. Apruebas un código corto en un navegador en cualquier dispositivo y la conexión actúa como tú.

Crear un agente desatendido​

  1. Abra el espacio de trabajo y vaya a Configuración del espacio de trabajo -> API.
  2. en el Agentes de IA desatendidos sección, ingrese un Nombre.
  3. Elige un Alcance máximo: leer, escribir, o Administrador. El agente puede solicitar este alcance o inferior, nunca superior.
  4. Elige Crear conexión de agente.
  5. Copie las credenciales que se muestran una vez: client_id, client_secret, y token_url. Guárdalos en el administrador secreto de tu agente. Kanera nunca vuelve a mostrar el secreto.

La creación de un agente desatendido requiere acceso de administrador del espacio de trabajo. En Kanera alojado también requiere Pro o la versión de prueba Pro, y una degradación a Gratis lo desactiva hasta que la organización actualice nuevamente.

Administrador agrega gestión de automatización dentro del espacio de trabajo de la conexión: crear, editar, habilitar y eliminar reglas. No permite la creación de espacios de trabajo ni la administración general de tableros, listas, campos, etiquetas o membresías a través de MCP. Una regla habilitada puede publicar comentarios o enviar datos de tarjetas y listas a un punto final de webhook externo configurado; inspeccionar sus acciones antes de habilitarlo. Utilice una integración REST compatible para la administración no expuesta por una herramienta MCP.

Configuración de la API del espacio de trabajo para crear un agente de IA desatendido con un nombre y alcance máximo.

Utilice un agente desatendido​

Cambie la identificación y el secreto del cliente por un token de acceso MCP de corta duración y luego configure el agente para usarlo con el servidor MCP. el resource El valor es la dirección MCP exacta mostrada por Kanera.

# 1. Get an access token (valid for 15 minutes).
curl -X POST https://api.kanera.app/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=kanera:read \
  -d resource=https://mcp.kanera.app/mcp

# Response: { "access_token": "kanera_mcp_...", "token_type": "Bearer", "expires_in": 900, "scope": "kanera:read" }

Configure el agente para llamar al punto final MCP con:

Authorization: Bearer kanera_mcp_...

Los agentes desatendidos no reciben un token de actualización. Solicite un nuevo token de acceso cuando caduque el actual. El alcance solicitado siempre está limitado al alcance máximo que eligió al crear la conexión. Utilice una clave API de tablero o espacio de trabajo cuando una integración desatendida personalizada necesite llamar directamente a la API REST pública.

Para revocar un agente desatendido, elimínelo del Agentes de IA desatendidos lista. Sus tokens y la credencial del espacio de trabajo subyacente dejan de funcionar inmediatamente.

Para clientes OAuth personalizados​

Los clientes compatibles manejan este flujo automáticamente. Si está creando su propio cliente, los requisitos importantes son:

  • Descubra el servidor de autorización a partir de los metadatos anunciados por el punto final de MCP.
  • Utilice PKCE con una dirección de redireccionamiento registrada exacta.
  • Envíe la dirección MCP exacta como resource durante la autorización y cada token o intercambio de actualización.
  • Envíe el token de acceso resultante solo a esa dirección MCP, no a /api/v1.

Ver el Referencia técnica del MCP para autorización de dispositivos y ejemplos de solicitudes.

La actualización desde una versión que emitió tokens OAuth independientes revoca las concesiones y tokens existentes porque no tienen una audiencia MCP confiable. Las definiciones de clientes registrados permanecen, pero cada usuario o cliente desatendido debe conectarse nuevamente una vez después de esa migración anterior de vinculación de audiencia. El cambio de política de lectura/escritura no revoca las conexiones actuales: las sesiones OAuth válidas existentes pasan a tener capacidad de escritura después de que se actualiza el servidor y no es necesario volver a conectarse.

Solución de problemas​

problemaQue comprobar
El cliente solicita una clave API en lugar de abrir un navegador.El cliente no admite MCP OAuth remoto. Utilice un Clave de API en cambio.
"Las claves API de Workspace y los agentes de IA desatendidos no están disponibles en su plan".Los agentes de servicio desatendidos necesitan Pro o la versión de prueba Pro. Actualice la organización o conéctese interactivamente como usted mismo, lo que funciona en todos los planes.
El paso de consentimiento del navegador falla o la conexión es "no válida o caducada".Reinicie la conexión desde el cliente. Los códigos de autorización son de un solo uso y caducan después de cinco minutos.
El punto final del token regresa invalid_target.Asegúrese de que el cliente envíe la dirección MCP exacta desde Configuración de perfil -> Claves API como resource durante la autorización y cada intercambio de tokens.
Una conexión OAuth que funcionaba anteriormente falla inmediatamente después de actualizar desde una versión de token independiente.Vuelva a conectarlo una vez. Sólo la migración más antigua, vinculante para la audiencia, revoca intencionalmente subvenciones y tokens no consolidados; la actualización de la política de lectura/escritura no.
El agente se conecta pero no puede editar.Confirme que el cliente permita la acción de escritura y que su usuario de Kanera sea un editor en el tablero de destino. Los observadores no pueden escribir. La creación de espacios de trabajo o tableros y la gestión de automatizaciones también necesitan la función de administrador correspondiente. Si la organización del consejo ha fijado su Política de agente de IA a Sólo lectura, los agentes no pueden escribir allí en absoluto.
"El acceso de los agentes de IA está desactivado para esta organización".Un administrador de la organización propietaria del tablero ha establecido su Política de agente de IA a Apagado. Pídales que lo cambien; volver a conectar al agente no ayuda.
Un agente desatendido recibe 403 a pedido.El alcance solicitado excede el alcance máximo de la conexión o la credencial del espacio de trabajo ya no tiene acceso.