Conecte um agente de IA

Conecte um agente de IA ao Kanera com OAuth interativo, uma conexão de serviço autônoma ou uma chave de API. O método correto depende se o agente atua como pessoa, funciona sem supervisão ou oferece suporte apenas a credenciais estáticas.

Para ChatGPT ou uma superfície Codex compatível, instale o Kanera plugin e conecte sua conta por meio do prompt OAuth. Siga Configurar ChatGPT ou Configurar o Codex; o plugin inclui a habilidade Kanera e conexão MCP.

Para outros assistentes pessoais, use OAuth quando seu cliente oferecer suporte a MCP remoto com autenticação de navegador. Você adiciona o endereço MCP de Kanera, aprova a conexão e o agente age como você, respeitando sua função em cada fórum. Use uma conexão autônoma para CI ou automação do lado do servidor, ou um Chave de API quando o cliente não suporta OAuth.

Configuração rápida para agentes de codificação

Cole isso no Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode ou outro agente de codificação:

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

O prompt instala a habilidade oficial do agente Kanera, registra o servidor MCP hospedado usando a configuração do agente atual e inicia o OAuth onde o cliente o suporta. Revise a tela de consentimento do navegador antes de aprovar o acesso.

Escolha um método de conexão

Conexão	Quem atua como	Onde você configurou	Melhor para
OAuth (interativo)	Você, após uma tela de consentimento do navegador. Nenhuma chave de API.	Você adiciona o endereço MCP ao seu agente; Kanera cuida do login e do consentimento. Gerencie em Configurações de perfil -> Chaves de API.	Um assistente pessoal de IA em Claude, ChatGPT, Copilot ou Codex.
OAuth (código do dispositivo)	Você, após aprovar um código curto em um navegador. Nenhuma chave de API.	O cliente mostra um código; você aprova no Kanera Conecte um dispositivo página. Gerencie em Configurações de perfil -> Chaves de API.	Uma CLI, sessão SSH ou máquina headless que não consegue abrir um redirecionamento de navegador.
Agente autônomo (conexão de serviço)	Uma identidade de serviço de espaço de trabalho, leitura, gravação ou administração com escopo.	Configurações do espaço de trabalho -> API, "Agentes de IA autônomos".	CI, cron jobs ou um agente do lado do servidor sem nenhum humano para clicar em Permitir.
Chave de API	O proprietário da chave (pessoal) ou o espaço de trabalho (chave do espaço de trabalho).	Configurações de perfil -> Chaves de API ou Configurações do espaço de trabalho -> API.	MCP de stdio local ou clientes que não suportam OAuth.

Requisitos

Seu cliente de IA deve oferecer suporte a servidores MCP remotos com OAuth. Os clientes que suportam apenas um token de portador estático devem usar um Chave de API em vez disso.
As conexões de agentes interativos funcionam em todos os planos Kanera, incluindo o Gratuito. Nos fóruns de uma organização Livre, os agentes de cada pessoa compartilham um limite de 5 solicitações por segundo e 60 por minuto; As quadros Pro permitem 20 e 400. Consulte Limites de taxa.

Como posso saber se meu agente oferece suporte a OAuth?

Não existe uma lista fixa e o suporte ao cliente muda com o tempo, então a verificação confiável é tentar:

Adicione o endereço MCP da Kanera ao seu cliente como um servidor MCP remoto ou personalizado.
Se o cliente suportar OAuth, ele abrirá uma guia do navegador Kanera para login e consentimento. Essa é a sua confirmação.
Se o cliente solicitar uma chave de API, um token ou um Authorization cabeçalho ou simplesmente não consegue se conectar, ele não suporta OAuth. Use um Chave de API em vez disso.

Os clientes que descrevem suporte para "servidores MCP remotos", "conectores personalizados" ou "OAuth" geralmente funcionam. Para um cliente que executa apenas servidores stdio locais, aponte para kanera mcp do Kanera CLI depois kanera auth login; ele retransmite o servidor hospedado com seu login OAuth, portanto, você ainda não precisa de uma chave.

Conecte um agente (interativo)

Abrir Configurações de perfil -> Chaves de API.
No Conexão do agente de IA seção, copie o Endereço MCP. Para o serviço hospedado de Kanera é:
```
https://mcp.kanera.app/mcp
```
Adicione esse endereço ao seu cliente AI como um servidor MCP remoto. Abaixo Ou configure-o manualmente, escolha Claude Code, Cursor, VS Code/GitHub Copilot, Codex ou Gemini CLI para copiar um comando ou configuração pronta com seu endereço MCP já preenchido. Para outros clientes, siga as etapas do próprio cliente para adicionar um conector MCP personalizado ou remoto.
O cliente abre uma guia do navegador Kanera. Faça login, se ainda não tiver feito isso, e revise a tela de consentimento.
Escolha Permitir acesso. Kanera leva você de volta ao agente, que agora está conectado.

Você não insere uma chave de API em nenhum momento. O agente recebe um token de acesso de curta duração e o atualiza automaticamente em segundo plano.

OAuth conecta as ferramentas; ele por si só não ensina ao cliente fluxos de trabalho específicos do Kanera. Se o seu cliente oferece suporte a Agent Skills, instale também o Habilidade do agente Kanera:

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

A habilidade orienta o agente a ler o estado atual, resolver IDs estáveis, fazer alterações solicitadas com segurança e lidar corretamente com falhas de autenticação ou permissão. Consulte os guias de configuração específicos do cliente nesta seção para obter locais de habilidades manuais.

A tela de consentimento nomeia o agente e explica o limite da conexão. Um agente conectado desta forma irá:

Leia quadros, cartões, notas, comentários e atividades que você pode acessar.
Criar e atualizar o conteúdo do quadro onde quer que você seja um editor.
Criar e administrar espaços de trabalho onde quer que você seja um administrador: como administrador da organização, ele pode criar espaços de trabalho e quadros independentes e, como administrador do espaço de trabalho, pode adicionar quadros a esse espaço de trabalho e criar, editar, ativar e excluir suas automações. Outras administrações, como edição de listas, campos, rótulos e membros, permanecem na interface do Kanera.

Kanera usa estes escopos OAuth para agentes autorizados pelo usuário:

Escopo	Subsídios
`kanera:read`	Leia o conteúdo do quadro que você pode acessar.
`kanera:write`	Crie e atualize o conteúdo do quadro onde você é editor.
`offline_access`	Aceito quando um cliente solicita. Kanera emite um token de atualização sempre que o cliente se registra para atualização, para que o agente possa permanecer conectado sem solicitar que você faça login novamente.

Conexões interativas e de código de dispositivo sempre recebem kanera:read e kanera:write, mesmo quando um cliente omite escopos ou solicita apenas leitura. Isso mantém o servidor compatível com clientes que lidam com permissões de ação de maneira diferente. O cliente de IA continua responsável por decidir quais ferramentas o usuário pode acessar e quando exigir confirmação. Kanera verifica independentemente a função atual do usuário conectado em cada solicitação, portanto, um Observador não pode gravar em um quadro. Na nuvem Kanera, o política de agente de IA da organização também pode tornar os agentes somente leitura ou desativá-los nos quadros de uma organização. offline_access permanece opcional porque controla a atualização do token em vez das permissões da ferramenta Kanera.

Gerenciar e desconectar agentes

Abrir Configurações de perfil -> Chaves de API e encontre o Conexão do agente de IA seção.

Cada agente conectado mostra seu nome, seus escopos concedidos e quando se conectou.
Escolha Desconectar agente para revogar uma conexão. Seus tokens de acesso e atualização param de funcionar imediatamente, então o agente perde o acesso imediatamente.

Desconectar é a maneira mais rápida de desligar um cliente de IA que você não usa ou não confia mais.

Agentes autônomos (conexões de serviço)

OAuth interativo precisa que uma pessoa clique Permitir. Para CI, tarefas cron ou um agente personalizado do lado do servidor sem presença humana, crie um agente autônomo nas configurações do espaço de trabalho. Ele autentica com um ID de cliente e segredo usando o OAuth client_credentials concessão.

Se uma pessoa estiver presente, mas o cliente não puder abrir um redirecionamento do navegador, como uma CLI ou uma sessão SSH, use autorização do dispositivo em vez disso. Você aprova um código curto em um navegador em qualquer dispositivo e a conexão age como você.

Crie um agente autônomo

Abra a área de trabalho e vá para Configurações do espaço de trabalho -> API.
No Agentes de IA autônomos seção, insira um Nome.
Escolha um Escopo máximo: Leia, Escreva, ou Administrador. O agente pode solicitar este escopo ou inferior, nunca superior.
Escolha Criar conexão de agente.
Copie as credenciais mostradas uma vez: client_id, client_secrete token_url. Armazene-os no gerenciador secreto do seu agente. Kanera nunca mais mostra o segredo.

A criação de um agente autônomo requer acesso de administrador do espaço de trabalho. No Kanera hospedado, ele também requer o Pro ou o teste Pro, e um downgrade para Free o desativa até que a organização atualize novamente.

Administrador adiciona gerenciamento de automação no espaço de trabalho da conexão: crie, edite, habilite e exclua regras. Ele não permite a criação de espaço de trabalho ou administração de quadro geral, lista, campo, rótulo ou associação por meio do MCP. Uma regra habilitada pode publicar comentários ou enviar dados de cartão e lista para um endpoint de webhook externo configurado; inspecione suas ações antes de ativá-lo. Use uma integração REST suportada para administração não exposta por uma ferramenta MCP.

Use um agente autônomo

Troque o ID e o segredo do cliente por um token de acesso MCP de curta duração e, em seguida, configure o agente para usá-lo com o servidor MCP. O resource o valor é o endereço MCP exato mostrado 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 o agente para chamar o terminal MCP com:

Authorization: Bearer kanera_mcp_...

Os agentes autônomos não recebem um token de atualização. Solicite um novo token de acesso quando o atual expirar. O escopo solicitado é sempre limitado ao escopo máximo escolhido ao criar a conexão. Use uma chave de API de espaço de trabalho ou quadro quando uma integração autônoma personalizada precisar chamar diretamente a API REST pública.

Para revogar um agente não atendido, exclua-o da lista Agentes de IA autônomos lista. Seus tokens e a credencial do espaço de trabalho subjacente param de funcionar imediatamente.

Para clientes OAuth personalizados

Clientes compatíveis lidam com esse fluxo automaticamente. Se você estiver construindo seu próprio cliente, os requisitos importantes são:

Descubra o servidor de autorização a partir dos metadados anunciados pelo terminal MCP.
Use PKCE com um endereço de redirecionamento registrado exato.
Envie o endereço MCP exato como resource durante a autorização e cada token ou troca de atualização.
Envie o token de acesso resultante apenas para esse endereço MCP, não para /api/v1.

Veja o Referência técnica do MCP para autorização de dispositivos e exemplos de solicitação.

A atualização de uma versão que emitiu tokens OAuth não vinculados revoga concessões e tokens existentes porque eles não têm um público MCP confiável. As definições de cliente registrado permanecem, mas cada usuário ou cliente autônomo deve se conectar novamente uma vez após a migração mais antiga de vinculação de público. A alteração da política de leitura/gravação não revoga as conexões atuais: as sessões OAuth válidas existentes tornam-se capazes de gravação depois que o servidor é atualizado e não precisam se reconectar.

Solução de problemas

Problema	O que verificar
O cliente pede uma chave API em vez de abrir um navegador.	O cliente não oferece suporte ao MCP OAuth remoto. Use um Chave de API em vez disso.
"As chaves de API do Workspace e os agentes de IA autônomos não estão disponíveis no seu plano."	Os agentes de serviço autônomo precisam do Pro ou da versão de avaliação do Pro. Atualize a organização ou conecte-se interativamente como você mesmo, o que funciona em todos os planos.
A etapa de consentimento do navegador falha ou a conexão é “inválida ou expirada”.	Reinicie a conexão do cliente. Os códigos de autorização são de uso único e expiram após cinco minutos.
O ponto final do token retorna `invalid_target`.	Certifique-se de que o cliente envie o endereço MCP exato de Configurações de perfil -> Chaves de API como `resource` durante a autorização e cada troca de token.
Uma conexão OAuth que funcionava anteriormente falha imediatamente após a atualização de uma versão de token não vinculado.	Reconecte-o uma vez. Somente a migração mais antiga, vinculada ao público, revoga intencionalmente concessões e tokens não vinculados; a atualização da política de leitura/gravação não.
O agente se conecta, mas não pode editar.	Confirme se o cliente permite a ação de gravação e se o seu usuário Kanera é um Editor no quadro de destino. Os observadores não podem escrever. A criação de espaços de trabalho ou quadros e o gerenciamento de automações também precisam da função de administrador correspondente. Se a organização do quadro tiver definido o seu Política de agente de IA para Somente leitura, os agentes não podem escrever lá.
"O acesso do agente de IA está desativado para esta organização."	Um administrador da organização proprietária do quadro definiu seu Política de agente de IA para Desligado. Peça-lhes para mudarem; reconectar o agente não ajuda.
Um agente autônomo obtém `403` a pedido.	O âmbito solicitado excede o âmbito máximo da ligação ou a credencial do espaço de trabalho já não tem acesso.

Configuração rápida para agentes de codificação​

Escolha um método de conexão​

Requisitos​

Como posso saber se meu agente oferece suporte a OAuth?​

Conecte um agente (interativo)​

O que você aprova na tela de consentimento​

Gerenciar e desconectar agentes​

Agentes autônomos (conexões de serviço)​

Crie um agente autônomo​

Use um agente autônomo​

Para clientes OAuth personalizados​

Solução de problemas​

Páginas relacionadas​