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.

When the Kanera plugin is available in Codex, prefer installing or attaching that plugin: it bundles the Kanera app connection and the Kanera skill so card requests route to MCP instead of generic browser automation. A standalone MCP connection still works, but install the skill separately as described below.

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 Kanera skill​

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 kanera_get_card and apply the requested change through kanera_update_card. It should open the Kanera web interface only for an explicitly visual task or an administration operation that MCP does not expose.

Connect with an API key​

Use an API key for a local stdio server, or as a fallback when remote OAuth is unavailable. 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:

[mcp_servers.kanera]
command = "pnpm"
args = ["--filter", "@kanera/mcp", "stdio"]
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 \
  -- pnpm --filter @kanera/mcp stdio

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​