Skip to main content

Set up Codex for Kanera MCP

The Codex desktop app, CLI, and IDE extension connect to Kanera through the Model Context Protocol. They share the same config.toml, so you only need to add Kanera once.

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 desktop app or IDE extension, add a Streamable HTTP server with the same URL. When Kanera shows that authentication is required, choose Authenticate. The app, CLI, and IDE extension share the resulting MCP configuration.

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 optional Kanera agent skill teaches it how to use those tools reliably: resolve names to stable IDs, read live state before reporting or changing work, distinguish completed work from newly created 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.

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.

Codex desktop app​

Open Settings -> Integrations & MCP, then add a custom server. You can add the local stdio server there, or edit config.toml using the configuration below. The app saves MCP settings in the same configuration used by Codex CLI and the IDE extension.

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 -> Integrations & MCP to check the connection.