OpenAI Codex CLI + Knowi

Connect OpenAI's Codex CLI to Knowi's MCP server. Once connected, you can query data, manage dashboards, and automate Knowi operations from Codex.

Prerequisites

• Codex CLI installed (npm install -g @openai/codex)
• Knowi account with AI Agents enabled

Option A: OAuth Browser Auth (Recommended)

The easiest way to connect - no token copy/paste needed.

Edit ~/.codex/config.json:

{
  "mcpServers": {
    "knowi": {
      "type": "http",
      "url": "https://www.knowi.com/api/2.0/mcp"
    }
  }
}

The first time Codex uses the connection, it will open your browser to sign in to Knowi and authorize access.

Instance URL: Use the URL that matches your Knowi deployment:

• Knowi Cloud (default): https://www.knowi.com
• EU Cloud: https://eu.knowi.com
• On-Premise: Your on-premise Knowi URL (e.g. https://knowi.yourcompany.com)

Option B: Manual Token

If you prefer to manage the token manually:

1. Log into Knowi. Navigate to Settings > AI Settings.
2. Under MCP Token, select a token expiry and click Generate Token. Copy the token.

3. Edit ~/.codex/config.json:

   {
     "mcpServers": {
       "knowi": {
         "type": "http",
         "url": "https://www.knowi.com/api/2.0/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_MCP_TOKEN"
         }
       }
     }
   }
   

Verify

Start a new Codex session and ask:

"What Knowi tools are available?"

You should see the full list of Knowi tools including knowi_do, knowi_ask, knowi_list_dashboards, and others.

Usage

Interact with Knowi using natural language from Codex:

"Show me my Knowi dashboards"
"Ask Knowi: what is our monthly recurring revenue trend?"
"Export Knowi dashboard 67890 to CSV"

Troubleshooting

Tools not appearing

1. Verify your config file path and JSON syntax.
2. Check that the Knowi instance is reachable: curl https://www.knowi.com/api/2.0/mcp/health
3. Verify your token: curl -H "Authorization: Bearer YOUR_MCP_TOKEN" https://www.knowi.com/api/2.0/mcp/tools

Token expired

Generate a new token from Settings > AI Settings > MCP Token, then update ~/.codex/config.json.

For full tool documentation, see MCP Server.