KSI MCP – Connecting Your AI Assistant

Objective

This guide walks you through connecting an AI assistant (Claude, ChatGPT, Gemini, or any MCP-compatible client) to the KSI MCP server, so it can query your stores' indicators directly — traffic, queues, dwell time, sales conversion, zones, and more — and turn them into reports, comparisons, and analyses in natural language.

MCP (Model Context Protocol) is the open standard that lets AI assistants call external tools securely. The KSI MCP server exposes your account's data as a set of tools; your assistant decides when to call them based on what you ask.

Requirements

Before connecting, make sure you have:

A valid user account in the KSI platform
Your KSI API token (see API – Getting Started Guide)
An MCP-compatible AI client (Claude, ChatGPT, Gemini, or another MCP client)

👉 MCP Server URL:

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

1. Get Your API Token

The MCP server authenticates with the same Bearer token used by the KSI API.

Go to "My Profile" in the KSI platform
Select "Generate new token"
Copy the token and store it securely — treat it like a password

Each user should connect with their own token: the assistant will only see the stores and data that token has access to.

Most AI apps and web clients support OAuth 2.1 with automatic discovery. You only need the server URL — the client will guide you to a KSI login screen the first time.

In your AI assistant, look for Settings → Connectors (or Integrations / Tools, depending on the client)
Choose "Add custom connector" and enter the MCP server URL: https://sandbox.ksivision.com/api/mcp
The client opens the KSI login screen automatically
Paste your API token and select Authorize
You are redirected back to your assistant — the connector is now active

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).

3. Connect with a Static Bearer Token — Claude Code, custom integrations

Some clients (developer CLIs, custom scripts, API integrations) connect with a fixed header instead of an interactive login.

Claude Code (CLI)

claude mcp add --transport http ksi https://sandbox.ksivision.com/api/mcp \
  --header "Authorization: Bearer <YOUR_KSI_TOKEN>"

Generic HTTP MCP client (config file)

{
  "mcpServers": {
    "ksi": {
      "type": "http",
      "url": "https://sandbox.ksivision.com/api/mcp",
      "headers": { "Authorization": "Bearer <YOUR_KSI_TOKEN>" }
    }
  }
}

4. First Steps After Connecting

Always start with the account diagnostic tool. Ask your assistant:

"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). Tenants vary a lot — this tells your assistant what it can safely ask for before running an analysis.

Example prompts

"Compare traffic and conversion across my stores in June, grouped by tag."
"In which day-and-hour windows am I losing sales to long queues at store 661?"
"Would opening more checkouts improve conversion at peak hours?"
"Rank the stores in my mall by conversion, grouped by category."

5. Checklist Before Using the MCP

You have a valid KSI API token
You confirmed the MCP server URL: https://sandbox.ksivision.com/api/mcp
You completed the login (OAuth) or configured the static Bearer header
You ran ksi_diagnose_account (or asked your assistant to "diagnose my account") before requesting KPIs
You understand the token is personal — each user connects with their own

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
The assistant only sees the stores and data your token has access to

Support

If you need help connecting your AI assistant, generating a token, or troubleshooting a specific client:

📧 ksi.support@ksivision.com

The KSI support team can assist with technical guidance and best practices.