MCP technical reference

Use this page when you need transport details, static credentials, self-hosted setup, capability boundaries, or protocol troubleshooting. For the shortest personal setup, start with Connect Kanera to your AI agent.

Connection methods

Connection	Authentication	Effective access
Interactive OAuth	Browser sign-in and consent	Acts as the connected user with the granted Read and optional Write scopes. It never receives workspace administration access.
Unattended agent	OAuth client_credentials	Uses a workspace service identity capped at the Read, Write, or Admin maximum chosen by a workspace administrator.
Personal API key	Static bearer token	Acts as its owner across the boards and workspaces they can access, including administration where the owner is an administrator.
Workspace or board API key	Static bearer token	Stays pinned to the standard workspace or standalone board where it was created and is limited to its Read, Write, or Admin scope.

See Connect an AI agent for interactive OAuth, consent, revocation, unattended agents, and the authorization flow.

Hosted endpoints

Kanera's hosted MCP endpoint is:

https://mcp.kanera.app/mcp

The service health check is:

https://mcp.kanera.app/health

OAuth-capable clients can add the MCP endpoint directly and complete authentication in the browser. A client using an API key sends it as a bearer token:

Authorization: Bearer kanera_live_...

A self-hosted deployment exposes the same /mcp and /health paths on its configured MCP origin. Copy the exact MCP address shown under Profile settings -> API keys in that deployment.

Create an API key

Use API keys for local stdio, clients that only accept static bearer tokens, or custom server-side integrations.

Personal API key

1. Open Profile settings.
2. Go to API keys.
3. Create a personal API key.
4. Add an optional private label that identifies the client.
5. Copy the secret when it is shown.

A personal key has a prefix such as kanera_u_live_.... It is shown once and acts as its owner. Store it only in the AI client's credential store or your server's secret manager.

Workspace or board API key

1. Open the standard workspace or standalone board.
2. Go to Settings -> API.
3. Create an API key.
4. Choose the smallest scope that fits the workflow.
5. Copy the secret when it is shown.

Scope	Grants
Read	Inspect, search, summarize, and report without changing Kanera.
Write	Create and update board content, including cards, checklists, comments, assignments, labels, custom field values, and notes.
Admin	Perform supported workspace or standalone-board administration. Use this only when the workflow requires it.

Connect a local stdio client

The local MCP package reads:

Environment variable	Purpose
KANERA_API_KEY	A personal, workspace, or board API key.
KANERA_PUBLIC_API_URL	The Kanera public API origin, such as https://api.kanera.app.

Example MCP configuration from the Kanera product repository:

{
  "mcpServers": {
    "kanera": {
      "command": "pnpm",
      "args": ["--filter", "@kanera/mcp", "stdio"],
      "env": {
        "KANERA_API_KEY": "kanera_u_live_...",
        "KANERA_PUBLIC_API_URL": "https://api.kanera.app"
      }
    }
  }
}

The pnpm --filter command expects a checkout of the Kanera product repository. Use the hosted HTTP endpoint when you do not need to run the MCP process locally.

Resources

Kanera provides four structured JSON resource templates:

Resource	URI	Contains
Standard workspace	kanera://workspace/{workspaceId}	Workspace configuration and shared lists, labels, fields, templates, automations, and membership visible to the credential
Board	kanera://board/{boardId}	A standard-workspace or standalone board with visible cards and configuration
Card	kanera://card/{cardId}	Card detail, including labels, assignees, checklists, attachments, and linked notes
Note	kanera://note/{noteId}	A visible personal or team note

Personal notes are private to the connected user. Do not imply that another workspace member or a workspace service credential can read them.

Capability groups

The live tool schemas are the authority for names, inputs, safety annotations, and limits. The server currently covers:

Area	Available operations
Discovery	Inspect the acting session, list standard workspaces, discover every accessible board, open workspace configuration, list members, and open standard or standalone boards
Administration	Create and update standard workspaces, create and configure standalone boards, create or move workspace boards, and manage lists, labels, custom fields, and select options
Search	Search live cards, notes, comments, and attachment filenames, or search the official Kanera documentation
Cards	Read summaries or full content, create, update, move, reorder, copy, move between compatible boards, archive, unarchive, complete, and reopen
Bulk card work	Complete, date, label, assign, move, archive, copy, or set custom fields on selected cards, with board-level batch limits exposed in each schema
Assignments and fields	Replace assignees or labels and set or clear supported custom-field values
Comments	List, add, bulk-add, and delete eligible comments
Checklists	Create, rename, reorder, delete, and manage checklist items, including supported bulk updates
Activity and completed work	Read recent board activity, completion history, and work-done records
Notes	List, read, create, update, link, attach small files, copy, and reorder personal or team notes

See the generated MCP tool inventory for every registered tool name.

Built-in prompts

Prompt	Use
summarize_board_status	Inspect one board and summarize progress, blockers, stale work, and next actions.
prepare_standup_update	Combine board-level work-done and completed-work records with active cards to draft a standup.
draft_card_from_notes	Read a note and draft a card title and Markdown description without creating the card.

Normal conversation prompts work even when an AI client does not expose MCP prompt templates.

Security and destructive operations

• Interactive OAuth requests kanera:read, optional kanera:write, and optional offline_access. It never grants workspace administration.
• Unattended agents and workspace keys are capped at their configured scope.
• Personal keys inherit their owner's current permissions and should be protected like the user's account.
• Read-only credentials cannot call protected mutations.
• API-key and MCP activity is recorded with its acting user or integration identity.
• Disconnecting OAuth or deleting an unattended agent revokes its active credentials.
• Use a separate credential per client so one connection can be revoked without affecting another.

Kanera MCP cannot delete:

• Boards
• Lists
• Labels or custom fields
• Notes
• Note attachments

Delete those manually in Kanera. MCP can archive or unarchive cards and can archive the active cards in a list.

MCP can permanently delete:

• A comment authored by the acting user
• An eligible group of comments authored by the acting user
• A checklist and its items
• A checklist item

Those tool schemas are marked destructive. Use them only after an explicit request and verify the target before calling them.

Troubleshooting

Problem	What to check
The client cannot connect	Use the exact /mcp URL. For self-hosting, copy the address shown by that deployment.
The client asks for a token instead of opening Kanera	It does not support remote MCP OAuth. Use an API key or a supported client.
The API key is reported missing	Set KANERA_API_KEY for stdio or send Authorization: Bearer ... over HTTP.
A request returns 401	The credential is missing, malformed, expired, revoked, or copied incorrectly. Restart OAuth or replace the API key.
A request returns 403	The identity cannot access the target or the credential does not have the required Write or Admin scope.
The agent can read but not edit	Approve OAuth Write access, use a Write-capable service credential, and confirm the acting identity has board editor access.
The agent cannot find a board	Use complete board discovery. A board may be standalone or available only through explicit guest membership.
The agent cannot administer a workspace over OAuth	Interactive OAuth intentionally blocks administration. Use a scoped unattended agent or API key when administration is required.
A coding agent has tools but uses them poorly	Install the official Kanera Agent Skill.
New or changed tools do not appear	Refresh or reconnect the MCP server in the client so it retrieves the current schemas.

Related pages

• Connect Kanera to your AI agent
• Connect with OAuth or an unattended agent
• Examples of how to use Kanera with AI
• MCP tool inventory
• Public API