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

Connection	Who it acts as	Where you set it up	Best 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.
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 key	The 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:

Add Kanera's MCP address to your client as a remote or custom MCP server.
If the client supports OAuth, it opens a Kanera browser tab for sign-in and consent. That is your confirmation.
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)

Open Profile settings -> API keys.
In the AI agent connection section, copy the MCP address. For Kanera's hosted service this is:
```
https://mcp.kanera.app/mcp
```
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.
The client opens a Kanera browser tab. Sign in if you are not already, then review the consent screen.
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.

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 lists exactly what it can do. 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. This line only appears when the agent requested write access.
Stay blocked from workspace and organisation administration. OAuth agents can never perform admin actions, even where you are an admin.

Kanera requests three OAuth scopes for interactive agents:

Scope	Grants
`kanera:read`	Read board content you can access.
`kanera:write`	Create and update board content where you are an editor.
`offline_access`	A refresh token so the agent can stay connected without asking you to sign in again.

An agent can request a narrower set, for example read-only. The consent screen always reflects what the agent actually asked for.

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.

Create an unattended agent

Open the workspace and go to Workspace settings -> API.
In the Unattended AI agents section, enter a Name.
Choose a Maximum scope: Read, Write, or Admin. The agent can request this scope or lower, never higher.
Choose Create agent connection.
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.

Use an unattended agent

Exchange the client id and secret for a short-lived access token at the token endpoint, then send that token as a bearer token to the MCP server or the public API.

# 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

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

# 2. Call the public API with the token.
curl "https://api.kanera.app/api/v1/workspaces" \
  -H "Authorization: Bearer kanera_oauth_..."

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.

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

How the OAuth flow works

You do not need these details to connect a supported client, but they help when configuring a custom agent.

The agent calls the MCP server without a token and receives a 401 with a WWW-Authenticate header pointing at Kanera's protected-resource metadata.
The agent fetches /.well-known/oauth-protected-resource from the MCP server to learn the authorization server.
The agent fetches /.well-known/oauth-authorization-server from the public API, registers itself, and starts an authorization-code flow with PKCE.
Kanera authenticates you in the browser and shows the consent screen. On approval the agent exchanges the code for a short-lived access token, plus a refresh token when offline_access was granted.
The agent calls the MCP server with Authorization: Bearer kanera_oauth_.... The MCP server forwards the token to the public API, which validates it.

Kanera enforces PKCE (S256), single-use authorization codes, exact-match redirect URIs, short-lived access tokens, and refresh-token rotation. OAuth access tokens are only accepted on the public API, never on the app's internal endpoints.

Troubleshooting

Problem	What 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 agent connects but cannot edit.	Approve the write scope, and confirm you have editor access on the boards involved. 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.

Quick setup for coding agents​

Choose a connection method​

Requirements​

How do I know if my agent supports OAuth?​

Connect an agent (interactive)​

What you approve on the consent screen​

Manage and disconnect agents​

Unattended agents (service connections)​

Create an unattended agent​

Use an unattended agent​

How the OAuth flow works​

Troubleshooting​

Related pages​