MCP Integration

Connect any MCP-compatible AI assistant to Kaelio for data research, metrics, dashboards, and knowledge management.

Kaelio exposes a remote Model Context Protocol (MCP) server that lets AI assistants research your data, query metrics, browse dashboards, and manage knowledge through natural conversation.

Any MCP client that supports the Streamable HTTP transport can connect — including Claude, Cursor, Windsurf, VS Code with GitHub Copilot, and others.

Before you start

Make sure you have:

A Kaelio instance with at least one connected data source
An API key — create one in Settings → API Keys

API keys have full access to all data sources, metrics, and dashboards. Keep them secure and rotate them regularly.

Connect your MCP client

Your MCP server URL

Your MCP server URL follows this pattern:

https://your-kaelio-instance.com/mcp

Replace your-kaelio-instance.com with your actual Kaelio URL. You can find the exact MCP URL in Settings → API Keys under the MCP Integration section.

Client setup

Go to Settings → API Keys in Kaelio and click Create API Key. Copy the key — it won't be shown again.

In Claude, open Settings → Integrations → Add custom integration.

Fill in the connector details:

Field	Value
Name	Kaelio
Remote MCP server URL	`https://your-kaelio-instance.com/mcp`
OAuth Client ID	Any string (e.g., `kaelio`)
OAuth Client Secret	Your Kaelio API key

Click Add to save.

The OAuth Client ID is required by the form but is not used for authentication — any non-empty value works. The OAuth Client Secret is where you paste your Kaelio API key.

Start a new conversation. Kaelio's tools are now available.

Add this to your Claude Desktop configuration file:

claude_desktop_config.json

{
  "mcpServers": {
    "kaelio": {
      "type": "streamable-http",
      "url": "https://your-kaelio-instance.com/mcp"
    }
  }
}

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

When Claude Desktop connects for the first time, it will open a browser window where you enter your Kaelio API key. After that, tokens are refreshed automatically.

claude mcp add kaelio --transport streamable-http https://your-kaelio-instance.com/mcp

On first use, Claude Code will open a browser for OAuth authorization where you enter your API key.

For non-interactive environments (CI, scripts), use a direct API key header instead:

claude mcp add kaelio --transport streamable-http \
  --header "X-API-Key: YOUR_API_KEY" \
  https://your-kaelio-instance.com/mcp

In Cursor, go to Settings → MCP Servers → Add new MCP server:

Type: streamable-http (or sse in older Cursor versions)
URL: https://your-kaelio-instance.com/mcp

If Cursor supports OAuth, it will open a browser for API key entry automatically. Otherwise, configure a custom header with your API key.

Cursor's MCP support is evolving — check Cursor's documentation for the latest configuration options.

Add this to your Windsurf MCP configuration file:

mcp_config.json

{
  "mcpServers": {
    "kaelio": {
      "serverUrl": "https://your-kaelio-instance.com/mcp"
    }
  }
}

Config file location:

macOS: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Windsurf's MCP support is evolving — check Windsurf's documentation for the latest configuration options.

VS Code supports MCP servers through GitHub Copilot's agent mode. Add this to your workspace or user settings:

.vscode/mcp.json

{
  "servers": {
    "kaelio": {
      "type": "http",
      "url": "https://your-kaelio-instance.com/mcp"
    }
  }
}

Requires the GitHub Copilot extension with agent mode enabled. Check VS Code's MCP documentation for the latest setup instructions.

For scripts, custom clients, or any HTTP-based integration, include your API key in every request using one of these headers:

# Option 1: Authorization header
curl -X POST https://your-kaelio-instance.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '...'

# Option 2: X-API-Key header
curl -X POST https://your-kaelio-instance.com/mcp \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '...'

Available tools

When connected, your AI assistant gets access to these Kaelio tools:

AI-powered actions

Tool	Description
research	Ask Kaelio to analyze your data. Kaelio searches the schema, writes SQL, executes queries, and generates visualizations. This is the primary tool.
execute-metric	Run a predefined KPI metric with specific measures, dimensions, filters, and time granularity.

Context reads

Tool	Description
list-connections	List all connected data sources (databases, warehouses, APIs).
list-metrics	List all defined KPI metrics with their measures and dimensions.
list-dashboards	Browse available dashboards.
get-dashboard	Get a dashboard's full structure — pages, widgets, and current data.
list-chats	Browse past research conversations.
get-chat	Retrieve a past conversation with its full message history.

Direct access

Tool	Description
execute-sql	Run a SQL query directly on a data connection. Use this for precise, targeted queries when the research tool is too broad.

Knowledge management

Tool	Description
list-knowledge	View knowledge blocks that inform Kaelio's research engine.
upsert-knowledge	Save business rules, data definitions, or domain expertise as knowledge for future research.
delete-knowledge	Remove knowledge blocks by key.

Example conversations

Once connected, try prompts like:

"What data sources are connected to Kaelio?" — uses list-connections
"Why did revenue drop last month?" — uses research, which runs Kaelio's full AI analysis pipeline
"Show me the monthly active users metric grouped by region" — uses list-metrics then execute-metric
"What dashboards do we have?" — uses list-dashboards
"Save a knowledge block: our fiscal year starts in April" — uses upsert-knowledge

Testing with MCP Inspector

The MCP Inspector is useful for testing your connection:

npx @modelcontextprotocol/inspector

Enter your Kaelio MCP URL and add an Authorization: Bearer <your-api-key> header to connect.

Authentication

Kaelio's MCP server supports OAuth 2.0 with PKCE (for interactive clients) and direct API key authentication (for programmatic access). Both methods use the same underlying API key.

OAuth flow

When an MCP client connects for the first time:

The client discovers Kaelio's OAuth endpoints via /.well-known/oauth-authorization-server
The client registers automatically via /register (dynamic client registration — no manual client ID needed)
A browser opens to Kaelio's /authorize page where you enter your API key
The server issues an authorization code, which the client exchanges at /token with PKCE verification
The client receives an access token (valid 1 hour) and refresh token (valid 30 days)
Token refresh happens automatically — no user interaction needed after initial setup

Direct API key

For scripts, testing, or clients that don't support OAuth, include your API key as a header in every request:

Authorization: Bearer <your-api-key>
X-API-Key: <your-api-key>

Both authentication methods use the same Kaelio API key. OAuth wraps it in a standard flow so the key is entered once and tokens are rotated automatically. Direct API key auth sends the key with every request.

MCP Integration

On this page