Skip to main content

Connect an AI agent

Connect an AI agent to Kanera with interactive OAuth, an unattended service connection, or an API key. The right method depends on whether the agent acts as a person, runs without supervision, or only supports static credentials.

For a personal assistant, use OAuth when your client supports remote MCP with browser authentication. You add Kanera's MCP address, approve the connection, and the agent acts as you while respecting your role on every board. Use an unattended connection for CI or server-side automation, or an API key when the client does not support OAuth.

Quick setup for coding agents​

Paste this into Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, or another coding agent:

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

The prompt installs Kanera's official Agent Skill, registers the hosted MCP server using the current agent's configuration, and starts OAuth where the client supports it. Review the browser consent screen before approving access.

Choose a connection method​

ConnectionWho it acts asWhere you set it upBest for
OAuth (interactive)You, after a browser consent screen. No API key.You add the MCP address to your agent; Kanera handles sign-in and consent. Manage it in Profile settings -> API keys.A personal AI assistant in Claude, ChatGPT, Copilot, or Codex.
OAuth (device code)You, after approving a short code in a browser. No API key.The client shows a code; you approve it on the Kanera Connect a device page. Manage it in Profile settings -> API keys.A CLI, SSH session, or headless machine that cannot open a browser redirect.
Unattended agent (service connection)A workspace service identity, scoped Read, Write, or Admin.Workspace settings -> API, "Unattended AI agents".CI, cron jobs, or a server-side agent with no human to click Allow.
API keyThe key's owner (personal) or the workspace (workspace key).Profile settings -> API keys or Workspace settings -> API.Local stdio MCP, or clients that do not support OAuth.

Requirements​

  • Your AI client must support remote MCP servers with OAuth. Clients that only support a static bearer token should use an API key instead.
  • Agent connections require a paid or trial Kanera plan. Free organisations get an upgrade prompt when they try to connect.

How do I know if my agent supports OAuth?​

There is no fixed list, and client support changes over time, so the reliable check is to try it:

  1. Add Kanera's MCP address to your client as a remote or custom MCP server.
  2. If the client supports OAuth, it opens a Kanera browser tab for sign-in and consent. That is your confirmation.
  3. If the client instead asks you for an API key, a token, or an Authorization header, or it simply fails to connect, it does not support OAuth. Use an API key instead.

Clients that describe support for "remote MCP servers", "custom connectors", or "OAuth" generally work. A local, stdio-only setup never uses OAuth; it always uses an API key.

Connect an agent (interactive)​

  1. Open Profile settings -> API keys.

  2. In the AI agent connection section, copy the MCP address. For Kanera's hosted service this is:

    https://mcp.kanera.app/mcp

  3. Add that address to your AI client as a remote MCP server. Follow the client's own steps for adding a custom or remote MCP connector.

  4. The client opens a Kanera browser tab. Sign in if you are not already, then review the consent screen.

  5. Choose Allow access. Kanera returns you to the agent, which is now connected.

You do not enter an API key at any point. The agent receives a short-lived access token and refreshes it automatically in the background.

Personal API settings showing the Kanera MCP address, agent setup prompt, and connected-agent management.

OAuth connects the tools; it does not by itself teach the client Kanera-specific workflows. If your client supports Agent Skills, also install the Kanera agent skill:

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

The skill guides the agent to read current state, resolve stable IDs, make requested changes safely, and handle authentication or permission failures correctly. See the client-specific setup guides in this section for manual skill locations.

The consent screen names the agent and explains the connection boundary. An agent connected this way will:

  • Read boards, cards, notes, comments, and activity you can access.
  • Create and update board content wherever you are an editor.
  • Stay blocked from workspace and organisation administration. OAuth agents can never perform admin actions, even where you are an admin.

Kanera uses these OAuth scopes for user-authorized agents:

ScopeGrants
kanera:readRead board content you can access.
kanera:writeCreate and update board content where you are an editor.
offline_accessA refresh token so the agent can stay connected without asking you to sign in again, when the client supports and requests refresh.

Interactive and device-code connections always receive kanera:read and kanera:write, even when a client omits scopes or requests only Read. This keeps the server compatible with clients that handle action permissions differently. The AI client remains responsible for deciding which tools the user can access and when to require confirmation. Kanera independently checks the connected user's current role on every request, so an Observer cannot write to a board. offline_access remains optional because it controls token refresh rather than Kanera tool permissions.

Manage and disconnect agents​

Open Profile settings -> API keys and find the AI agent connection section.

  • Each connected agent shows its name, its granted scopes, and when it connected.
  • Choose Disconnect agent to revoke a connection. Its access and refresh tokens stop working immediately, so the agent loses access right away.

Disconnecting is the fastest way to cut off an AI client you no longer use or trust.

Unattended agents (service connections)​

Interactive OAuth needs a person to click Allow. For CI, cron jobs, or a server-side custom agent with no human present, create an unattended agent in workspace settings. It authenticates with a client id and secret using the OAuth client_credentials grant.

If a person is present but the client cannot open a browser redirect, such as a CLI or an SSH session, use device authorization instead. You approve a short code in a browser on any device and the connection acts as you.

Create an unattended agent​

  1. Open the workspace and go to Workspace settings -> API.
  2. In the Unattended AI agents section, enter a Name.
  3. Choose a Maximum scope: Read, Write, or Admin. The agent can request this scope or lower, never higher.
  4. Choose Create agent connection.
  5. Copy the credentials shown once: client_id, client_secret, and token_url. Store them in your agent's secret manager. Kanera never shows the secret again.

Creating an unattended agent requires workspace admin access. On hosted Kanera it also requires a paid or trial plan.

The default MCP server exposes work tools, not administration tools, so choosing Admin currently adds no MCP capabilities beyond the work-focused surface. Use a separately issued workspace or board API key for a direct REST integration that needs a supported administration endpoint.

Workspace API settings for creating an unattended AI agent with a name and maximum scope.

Use an unattended agent​

Exchange the client id and secret for a short-lived MCP access token, then configure the agent to use it with the MCP server. The resource value is the exact MCP address shown by 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 the agent to call the MCP endpoint with:

Authorization: Bearer kanera_mcp_...

Unattended agents do not receive a refresh token. Request a new access token when the current one expires. The requested scope is always capped to the maximum scope you chose when creating the connection. Use a workspace or board API key when a custom unattended integration needs to call the public REST API directly.

To revoke an unattended agent, delete it from the Unattended AI agents list. Its tokens and the underlying workspace credential stop working immediately.

For custom OAuth clients​

Compatible clients handle this flow automatically. If you are building your own client, the important requirements are:

  • Discover the authorization server from the metadata advertised by the MCP endpoint.
  • Use PKCE with an exact registered redirect address.
  • Send the exact MCP address as resource during authorization and every token or refresh exchange.
  • Send the resulting access token only to that MCP address, not to /api/v1.

See the MCP technical reference for device authorization and request examples.

Upgrading from a release that issued unbound OAuth tokens revokes existing grants and tokens because they have no trustworthy MCP audience. Registered client definitions remain, but each user or unattended client must connect again once after that older audience-binding migration. The read/write policy change does not revoke current connections: existing valid OAuth sessions become write-capable after the server is upgraded and do not need to reconnect.

Troubleshooting​

ProblemWhat to check
The client asks for an API key instead of opening a browser.The client does not support remote MCP OAuth. Use an API key instead.
"API keys are not available on your plan."Agent connections require a paid or trial Kanera plan. Upgrade the organisation and try again.
The browser consent step fails or the connection is "invalid or expired".Restart the connection from the client. Authorization codes are single-use and expire after five minutes.
The token endpoint returns invalid_target.Ensure the client sends the exact MCP address from Profile settings -> API keys as resource during authorization and every token exchange.
A previously working OAuth connection fails immediately after upgrading from an unbound-token release.Reconnect it once. Only the older audience-binding migration intentionally revokes unbound grants and tokens; the read/write policy update does not.
The agent connects but cannot edit.Confirm the client allows the write action and that your Kanera user is an Editor on the target board. Observers cannot write, and OAuth agents can never perform admin actions.
An unattended agent gets 403 on a request.The requested scope exceeds the connection's maximum scope, or the workspace credential no longer has access.