Hopp til hovedinnholdet

Koble til en AI-agent

Koble en AI-agent til Kanera med interaktiv OAuth, en uovervåket tjenestetilkobling eller en API-nøkkel. Den riktige metoden avhenger av om agenten fungerer som en person, kjører uten tilsyn eller bare støtter statisk legitimasjon.

For ChatGPT eller en støttet Codex-overflate, installer Kanera plugin og koble kontoen din gjennom sin OAuth prompt. Følg Sett opp ChatGPT eller Sett opp Codex; plugin inkluderer Kanera ferdighet og MCP-tilkobling.

For andre personlige assistenter, bruk OAuth Når klienten din støtter fjernkontroll MCP med nettleserautentisering. Du legger til Kanera's MCP adresse, godkjenne tilkoblingen, og agenten fungerer som deg mens du respekterer din rolle på hver tavle. Bruk en uovervåket tilkobling for CI eller server-side automatisering, eller en API-nøkkel Når kunden ikke støtter OAuth.

Raskt oppsett for kodingsagenter​

Lim inn dette i Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode eller en annen kodeagent:

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

Den raske installasjonen Kanera's offisielle Agent Skill, registrerer verten MCP serveren bruker den gjeldende agentens konfigurasjon, og starter OAuth der klienten støtter det. Se gjennom nettleserens samtykkeskjerm før du godkjenner tilgang.

Velg en tilkoblingsmetode​

TilkoblingHvem det fungerer somHvor du setter det oppBest til
OAuth (interaktiv)Du, etter en nettleser samtykke skjerm. Ingen API-nøkkel.Du legger til MCP-adressen til agenten din; Kanera håndterer pålogging og samtykke. Profilinnstillinger -> API-nøkler.En personlig AI-assistent i Claude, ChatGPT, Copilot eller Codex.
OAuth (enhetskode)Du, etter å ha godkjent en kort kode i en nettleser. Ingen API-nøkkel.Klienten viser en kode; du godkjenner den på Kanera Koble til en enhet page. Administrer den i Profilinnstillinger -> API-nøkler.En CLI, SSH-økt eller hodeløs maskin som ikke kan åpne en nettleseromdirigering.
Ubetjent agent (tjenestetilkobling)En arbeidsområdetjenesteidentitet, som er definert Les, Skriv eller Admin.Arbeidsområdeinnstillinger -> API, "Ubetjente AI-agenter".CI, cron jobber, eller en server-side agent uten menneskelig å klikke Tillat.
API-nøkkelNøkkelens eier (personlig) eller arbeidsområdet (arbeidsplassnøkkel).Profilinnstillinger -> API-nøkler eller Arbeidsområdeinnstillinger -> API.Lokale stdio MCP, eller klienter som ikke støtter OAuth.

Krav​

  • AI-klienten må støtte eksterne MCP-servere med OAuth. Klienter som bare støtter et statisk bærertoken, bør bruke et API-nøkkel i stedet.
  • Interaktive agentforbindelser fungerer på alle Kanera Planen, inkludert Free. På en Free Organisasjonens tavle hver persons agenter deler en grense på 5 forespørsler per sekund og 60 per minutt; Pro tavlene tillate 20 og 400. Se Takstgrenser.

Hvordan vet jeg om agenten min støtter OAuth?​

Det er ingen fast liste, og klientstøtte endres over tid, så den pålitelige sjekken er å prøve det:

  1. Legg til Kanera's MCP adresse til klienten som en ekstern eller tilpasset MCP server.
  2. Hvis klienten støtter OAuth, åpnes en Kanera-nettleserfane for pålogging og samtykke. Det er bekreftelsen din.
  3. Hvis klienten i stedet ber deg om en API-nøkkel, et token eller en Authorization header, eller det rett og slett ikke klarer å koble, støtter det ikke OAuth. API-nøkkel i stedet.

Klienter som beskriver støtte for "fjern MCP-servere", "custom connectors" eller "OAuth" fungerer generelt. For en klient som bare kjører lokale stdio-servere, peker den på kanera mcp fra Kanera CLI etter kanera auth login; den videresender vertsserveren med OAuth-påloggingen, slik at du fortsatt ikke trenger en nøkkel.

Koble til en agent (interaktiv)​

  1. Åpne Profilinnstillinger -> API-nøkler.

  2. I vinduet AI agent tilkobling seksjonen, kopier MCP- adresse. For Kanera er vertstjenesten dette:

    https://mcp.kanera.app/mcp

  3. Legg til denne adressen i AI-klienten som en ekstern MCP-server. Under Eller konfigurere det for hånd, velg Claude Code, Cursor, VS Code / GitHub Copilot, Codex eller Gemini CLI for å kopiere en ferdig kommando eller konfigurasjon med din MCP-adresse allerede fylt ut. For andre klienter, følg kundens egne trinn for å legge til en tilpasset eller ekstern MCP-kontakt.

  4. Klienten åpner en Kanera-fane. Logg på hvis du ikke allerede er det, og gjennomgå deretter samtykkeskjermen.

  5. Velg Tillat tilgangKanera sender deg tilbake til agenten, som nå er koblet til.

Du trenger ikke å skrive inn en API-nøkkel på noe tidspunkt. Agenten mottar en kortvarig tilgang token og oppdaterer den automatisk i bakgrunnen.

Personlige API-innstillinger som viser agentoppsettsprompten, Kanera MCP-adressen, en kopieringsbar Claude Code-oppsettskommando og administrasjon av tilkoblet agent.

OAuth kobler verktøyene; det lærer ikke i seg selv klienten Kanera-spesifikke arbeidsflyter. Hvis klienten din støtter Agent Skills, må du også installere Kanera agent ferdigheter:

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

Ferdigheten veileder agenten til å lese gjeldende tilstand, løse stabile ID-er, gjøre forespurte endringer på en sikker måte og håndtere autentiserings- eller tillatelsesfeil på riktig måte. Se de klientspesifikke oppsettsveiledningene i denne delen for manuelle ferdighetsplasseringer.

Samtykkeskjermen navngir agenten og forklarer tilkoblingsgrensen. En agent som er koblet til på denne måten vil:

  • Les tavler, kort, notater, kommentarer og aktivitet du kan få tilgang til.
  • Opprette og oppdatere brettinnhold Uansett hvor du er redaktør.
  • Opprette og administrere arbeidsområder uansett hvor du er administrator: Som organisasjonsadministrator kan den opprette arbeidsområder og frittstående tavler, og som arbeidsområdeadministrator kan den legge til tavler i arbeidsområdet og opprette, redigere, aktivere og slette automatiseringene. Annen administrasjon, for eksempel redigeringslister, felt, etiketter og medlemmer, forblir i Kanera-grensesnittet.

Kanera bruker disse OAuth-omfangene for brukerautoriserte agenter:

VirkeområdeTilskudd
kanera:readLes innhold du kan få tilgang til.
kanera:writeOpprett og oppdater innhold på tavlen der du er redaktør.
offline_accessGodtatt når en klient ber om det. Kanera utsteder en oppdateringstoken når klienten registrerte seg for oppdatering, slik at agenten kan holde kontakten uten å be deg om å logge på igjen.

Interaktive tilkoblinger og enhetskodetilkoblinger mottar alltid kanera:read og kanera:write, selv når en klient utelater omfang eller ber bare om å lese. Dette holder serveren kompatibel med klienter som håndterer handlingstillatelser annerledes. AI-klienten er fortsatt ansvarlig for å bestemme hvilke verktøy brukeren kan få tilgang til og når den skal kreve bekreftelse. Kanera kontrollerer uavhengig den tilkoblede brukerens nåværende rolle på hver forespørsel, slik at en observatør ikke kan skrive til en tavle. På Kanera Cloud, organisasjon AI agent politikk kan også gjøre agenter skrivebeskyttet eller slå dem av for en organisasjons tavler. offline_access forblir valgfritt fordi det styrer token oppdatering i stedet for Kanera verktøy tillatelser.

Administrer og koble fra agenter​

Åpne Profilinnstillinger -> API-nøkler og finne AI agent tilkobling seksjon.

  • Hver tilkoblede agent viser sitt navn, sine tildelte omfang og når den koblet til.
  • Velg Koble fra agent for å tilbakekalle en tilkobling. Dens tilgang og oppdatere tokens slutter å fungere umiddelbart, slik at agenten mister tilgang med en gang.

Frakobling er den raskeste måten å kutte av en AI-klient du ikke lenger bruker eller stoler på.

Uovervåkede agenter (tjenestetilkoblinger)​

Interaktiv OAuth trenger en person å klikke Tillat. For CI, cron jobber, eller en server-side tilpasset agent uten menneskelig stede, opprette en ubemannet agent i arbeidsområdeinnstillinger. Det autentiserer med en klient-id og hemmelig ved hjelp av OAuth client_credentials tilskudd.

Hvis en person er til stede, men klienten ikke kan åpne en nettleseromdirigering, for eksempel en CLI- eller SSH-økt, kan du bruke enhetsautorisasjon i stedet. Du godkjenner en kort kode i en nettleser på en hvilken som helst enhet, og tilkoblingen fungerer som deg.

Opprette en uovervåket agent​

  1. Åpne arbeidsområdet og gå til Arbeidsområdeinnstillinger -> API.
  2. I vinduet Uovervåkede AI-agenter inndeling, skriv inn en Navn.
  3. Velg en Største omfang: Les, Skriv, eller AdministratorAgenten kan be om dette omfanget eller lavere, aldri høyere.
  4. Velg Opprett agentforbindelse.
  5. Kopier legitimasjonen som vises én gang: client_id, client_secret, og token_url. Lagre dem i agentens hemmelige manager. Kanera viser aldri hemmeligheten igjen.

Opprette en uovervåket agent krever arbeidsområde administratortilgang. På vert Kanera Det krever også Pro eller Pro rettssak, og en nedgradering til Free Dette vil ikke fungere før organisasjonen oppgraderes igjen.

Administrator legger til automatiseringsadministrasjon i tilkoblingens arbeidsområde: opprett, rediger, aktiver og slett regler. Det tillater ikke oppretting av arbeidsområde eller generell tavle, liste, felt, etikett eller medlemsadministrasjon via MCP. En aktivert regel kan publisere kommentarer eller sende kort og listedata til et konfigurert eksternt webhook-endepunkt. inspiser handlingene før du aktiverer det. Bruk en støttet REST-integrasjon for administrasjon som ikke er utsatt av et MCP-verktøy.

Arbeidsområde API-innstillinger for å opprette en uovervåket AI-agent med et navn og maksimalt omfang.

Bruk en uovervåket agent​

Utveksle klient-id og hemmelighet for en kortvarig MCP-tilgangstoken, og konfigurer deretter agenten til å bruke den med MCP-serveren. resource Verdien er den nøyaktige MCP-adressen som vises av 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" }

Konfigurer agenten til å ringe MCP-endepunktet med:

Authorization: Bearer kanera_mcp_...

Uovervåkede agenter mottar ikke et oppdateringstoken. Be om et nytt tilgangstoken når den nåværende utløper. Det forespurte omfanget er alltid begrenset til det maksimale omfanget du valgte når du opprettet tilkoblingen. Bruk en arbeidsområde eller tavle API-nøkkel når en tilpasset uovervåket integrasjon må ringe den offentlige REST API direkte.

Hvis du vil tilbakekalle en uovervåket agent, sletter du den fra Uovervåkede AI-agenter listen. Dens tokens og den underliggende arbeidsområdet legitimasjon slutte å fungere umiddelbart.

For egendefinerte OAuth-klienter​

Kompatible kunder håndterer denne flyten automatisk. Hvis du bygger din egen klient, er de viktige kravene:

  • Oppdag autorisasjonsserveren fra metadataene som annonseres av MCP-endepunktet.
  • Bruk PKCE med en nøyaktig registrert omdirigeringsadresse.
  • Send den eksakte MCP-adressen som resource under autorisasjon og hver token eller oppdateringsutveksling.
  • Send den resulterende tilgangstoken bare til den MCP-adressen, ikke til /api/v1.

Se på MCP teknisk referanse for enhetsautorisasjon og forespørselseksempler.

Oppgradering fra en utgivelse som utstedte ubundne OAuth-tokens tilbakekaller eksisterende tilskudd og tokens fordi de ikke har noen pålitelig MCP-publikum. Registrerte klientdefinisjoner forblir, men hver bruker eller ubemannet klient må koble til igjen etter den eldre publikumsbindende overføringen. Les / skriv policyendringen tilbakekaller ikke nåværende tilkoblinger: eksisterende gyldige OAuth-økter blir skrivekompatible etter at serveren er oppgradert og ikke trenger å koble til igjen.

Feilsøking​

ProblemHva du skal sjekke
Klienten ber om en API-nøkkel i stedet for å åpne en nettleser.Klienten støtter ikke ekstern MCP OAuth. Bruk en API-nøkkel i stedet.
Arbeidsplass-API-nøkler og uovervåkede AI-agenter er ikke tilgjengelige på planen din.Ubetjente serviceagenter trenger Pro eller Pro-prøveversjonen. Oppgrader organisasjonen, eller koble interaktivt til som deg selv, som fungerer på alle planer.
Nettleserens samtykketrinn mislykkes eller tilkoblingen er "ugyldig eller utløpt".Start tilkoblingen på nytt fra klienten. Autorisasjonskoder er engangsbruk og utløper etter fem minutter.
Token- endepunktet returnerer invalid_target.Sørg for at klienten sender den eksakte MCP-adressen fra Profilinnstillinger -> API-nøkler som resource under autorisasjon og hver token utveksling.
En tidligere fungerende OAuth-tilkobling mislykkes umiddelbart etter oppgradering fra en ubundet utgivelse.Bare den eldre publikumsbindende overføringen tilbakekaller med vilje ubundne tilskudd og tokens; Les / skriv policyoppdateringen gjør det ikke.
Agenten kobler til, men kan ikke redigere.Bekreft at klienten tillater skrivehandlingen og at Kanera-brukeren er en redaktør på måltavlen. Observatører kan ikke skrive. Opprette arbeidsområder eller tavler og administrere automatiseringer trenger også den matchende adminrollen. Hvis styrets organisasjon har satt sin AI agent politikk til SkrivebeskyttetDet er ikke mulig å skrive der i det hele tatt.
"AI-agenttilgang er slått av for denne organisasjonen."En administrator av organisasjonen som eier tavlen har satt sin AI agent politikk til Av. Be dem om å endre det; å koble agenten til igjen hjelper ikke.
En ubetjent agent får 403 på forespørsel.Det forespurte området overskrider tilkoblingens maksimale omfang, eller arbeidsområdets legitimasjon har ikke lenger tilgang.