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:
- Log into Knowi. Navigate to Settings > AI Settings.
- Under MCP Token, select a token expiry and click Generate Token. Copy the token.
-
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
- Verify your config file path and JSON syntax.
- Check that the Knowi instance is reachable:
curl https://www.knowi.com/api/2.0/mcp/health - 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.