Skip to main content

Setup Guide: KSI Vision MCP Server in Codex

This guide details the steps required to connect the KSI Vision Model Context Protocol (MCP) server to Codex, OpenAI's coding agent — both the Codex CLI and the Codex IDE extension (VS Code / Cursor), which share the same configuration file.

Once connected, Codex can query your stores' indicators directly — traffic, queues, dwell time, sales conversion, zones, and more — which is especially useful for building integrations, dashboards, or data pipelines on top of KSI data.

1. Prerequisites​

Before starting, make sure you have:

  • A KSI Vision account with access to create API Tokens (if you do not have access, request it at ksi.support@ksivision.com).
  • Your KSI API token (see API – Getting Started Guide).
  • Codex CLI installed and signed in (npm i -g @openai/codex or the IDE extension). Remote (HTTP) MCP servers require a recent version — update with codex --version / npm update -g @openai/codex if in doubt.

👉 MCP Server URL:

  • https://mcp.ksivision.com/api/mcp

2. Add the Server via Configuration File​

Codex reads its MCP configuration from:

  • File path: ~/.codex/config.toml (on Windows: C:\Users\<Your-Username>\.codex\config.toml)

Add the following block:

[mcp_servers.ksi]
url = "https://mcp.ksivision.com/api/mcp"

If you already have other servers configured, simply add the [mcp_servers.ksi] block below them. The IDE extension uses this same file, so the server becomes available there too.

3. Authentication​

Option A – OAuth login (recommended)​

  1. In your terminal, run:

    codex mcp login ksi

  2. Your browser opens the KSI login screen.

  3. Paste your KSI API token and select Authorize.

  4. Back in the terminal, the server shows as authenticated.

You will not need to paste the token again until it expires (access tokens last 30 days and refresh automatically while you keep using the connector).

Option B – Static Bearer token (headless / CI environments)​

Reference an environment variable that holds your token — do not write the token itself into the file:

[mcp_servers.ksi]
url = "https://mcp.ksivision.com/api/mcp"
bearer_token_env_var = "KSI_TOKEN"

Then set the variable in your shell before starting Codex:

# macOS / Linux
export KSI_TOKEN="<YOUR_KSI_TOKEN>"

# Windows (PowerShell)
$env:KSI_TOKEN = "<YOUR_KSI_TOKEN>"
note

MCP support in Codex evolves quickly and command flags may vary between versions. Run codex mcp --help to see the options available in your version — you can also manage servers with codex mcp add / codex mcp list instead of editing the file manually.

4. Verification​

  1. Start a Codex session (codex in your terminal, or open the IDE extension).
  2. Run /mcp to confirm the ksi server appears as connected and its tools are listed.
  3. Ask your first question:

"Diagnose my KSI account."

This returns your space type (retail, mall, airport…), the account's global feature flags, and which capabilities each store has (sales, queues, zones, sub-locations) — so Codex knows what it can safely ask for before running an analysis.

Example prompts​

  • "Compare traffic and conversion across my stores in June, grouped by tag."
  • "Fetch last week's traffic per store and build a CSV summary."
  • "In which day-and-hour windows am I losing sales to long queues at store 661?"

Security Notes​

  • The MCP server is read-only: it queries indicators and never modifies configuration, cameras, or data.
  • Your token travels with each request and is never stored on the MCP server.
  • Codex only sees the stores and data your token has access to — each user should connect with their own token.

Support​

If you need help connecting Codex, generating a token, or troubleshooting:

📧 ksi.support@ksivision.com