Skip to main content

Set up Codex for Kanera MCP

The ChatGPT desktop app, Codex CLI, and Codex IDE extension connect to Kanera through the Model Context Protocol. They share MCP configuration for the same Codex host, so you normally only need to add Kanera once.

In the ChatGPT desktop app, open Plugins, search for Kanera by Happen Software Limited, and install it. Connect your Kanera account through OAuth when prompted, then start a new Codex chat and ask it to use Kanera. The plugin bundles the MCP connection and skill, so no separate skill installation or manual server registration is needed.

In Codex CLI, enter /plugins to open the plugin browser, install Kanera from an available marketplace, and start a new session. Account, workspace policies, and configured marketplace sources determine availability.

The IDE extension does not support plugins. Use the manual connection and standalone skill below for the IDE, a self-hosted Kanera deployment, or a client where plugins are unavailable. Avoid registering a second hosted server when the plugin is already connected.

Manual connection with OAuth​

For a remote connection, add Kanera's MCP address and authenticate in your browser. You do not need to create or store an API key.

codex mcp add kanera --url https://mcp.kanera.app/mcp
codex mcp login kanera

The login command opens Kanera in your browser. Sign in, review the requested access, and choose Allow access. Run codex mcp list to verify the server is registered, or use /mcp in the Codex CLI to inspect the connection.

In the ChatGPT desktop app, open Settings -> MCP servers -> Add server. In the IDE extension, open the gear menu and select MCP servers -> Add server. Enter Kanera, choose Streamable HTTP, and use the same URL. Save and restart when prompted, then choose Authenticate when Kanera requires sign-in.

You can also configure the remote server directly in ~/.codex/config.toml:

[mcp_servers.kanera]
url = "https://mcp.kanera.app/mcp"

Then run codex mcp login kanera. See Connect an AI agent for scopes and disconnecting an agent.

Install the skill for a manual connection​

If you installed the plugin, its bundled skill is already available. For a manual setup, the MCP connection gives Codex access to Kanera's tools. The Kanera agent skill teaches it how to select those tools reliably: route exact card keys such as DEV-938 directly to Kanera, prefer MCP over browser automation for supported work, resolve names to stable IDs, read live state before reporting or changing work, use idempotency keys, and handle permission or rate-limit failures safely.

Install the skill globally with the open Agent Skills installer:

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

For a manual installation, download the complete kanera skill directory, including SKILL.md and agents/openai.yaml, and place it in one of these locations:

  • ~/.agents/skills/kanera/ for a personal skill available across projects.
  • .agents/skills/kanera/ in a repository to share the skill with that project.

Codex normally detects skill changes automatically. If it does not appear, restart Codex. Mention $kanera explicitly in a prompt to force it to load, or let Codex select it automatically for Kanera work.

Use /apps to attach the Kanera app, /plugins to inspect whether the Kanera plugin and bundled skill are available, and /mcp verbose to confirm the tool connection. For example:

$kanera Update DEV-938 with the investigation findings and agreed implementation plan.

Codex should read that card through cards.get and apply the requested change through cards.update. It should open the Kanera web interface only for an explicitly visual task or an administration operation that MCP does not expose.

Exception: connect with an API key​

Use OAuth whenever you can

An API key is a long-lived secret that you store and rotate yourself, and work done with a personal key is recorded as you, without the via <agent> label. Use one only when OAuth genuinely cannot work:

  • Your Codex version cannot complete the remote OAuth flow.
  • You need a local stdio server and cannot use the Kanera CLI. kanera auth login signs in with OAuth, and kanera mcp serves stdio with that sign-in, no key required.
  • The machine has no browser for the sign-in. Try device authorization first if your client supports it.

When you do use a key, create it Read-only unless the agent must change work, and keep it in an environment variable rather than a committed file.

Replace kanera_live_... with a personal key from Profile settings -> API keys or a workspace key from Workspace settings -> API, and set KANERA_PUBLIC_API_URL to https://api.kanera.app. For a personal Codex setup, a personal key is usually the right fit because it follows your own board access across workspaces.

Workspace API settings where a workspace API key can be created for Kanera MCP.

ChatGPT desktop app​

Open Settings -> MCP servers, then select Add server. You can add the local stdio server there, or edit config.toml using the configuration below. Save the server and select Restart.

After adding Kanera, start a new conversation and confirm its tools are available.

Config file (app, CLI, and IDE extension)​

Codex stores user-level MCP servers in ~/.codex/config.toml. Add a [mcp_servers.kanera] table for a local stdio server, which runs the Kanera CLI as the server (Node 22 or later). If you already ran kanera auth login, you can omit env; kanera mcp reuses the stored credential.

[mcp_servers.kanera]
command = "npx"
args = ["-y", "@kanera/cli", "mcp"]
env = { KANERA_API_KEY = "kanera_live_...", KANERA_PUBLIC_API_URL = "https://api.kanera.app" }

For the hosted HTTP server with a static API key, keep the key in an environment variable rather than writing it into the file:

[mcp_servers.kanera]
url = "https://mcp.kanera.app/mcp"
bearer_token_env_var = "KANERA_API_KEY"

Set KANERA_API_KEY in the environment that launches Codex, then restart the app, CLI, or IDE extension.

Command line​

Or add it from the command line:

codex mcp add kanera \
  --env KANERA_API_KEY=kanera_live_... \
  --env KANERA_PUBLIC_API_URL=https://api.kanera.app \
  -- npx -y @kanera/cli mcp

In the desktop app, return to Settings -> MCP servers to check the connection. In the IDE extension, use the gear menu and select MCP servers.

Client reference​