MCP Server

Knowi exposes a Model Context Protocol (MCP) server that lets external AI tools - Claude, Cursor, Copilot, or any MCP-compatible client - operate Knowi programmatically. Instead of navigating the UI, your AI assistant creates dashboards, queries data, exports results, and manages reports through natural language.

The MCP server runs within Knowi's application server. No additional services to deploy.

For connecting AI tools, see the setup guides: Claude Code | Cursor | VS Code | ChatGPT | Codex CLI

Authentication

The MCP server supports three authentication methods.

Option 1: OAuth Browser Auth (Recommended)

MCP clients that support OAuth 2.1 (Claude Code, Cursor, VS Code, Codex CLI) can connect with a one-click browser flow - no manual token copy/paste needed.

1. Add Knowi as an MCP server in your AI tool using just the URL (no token required).
2. When you first use the connection, the AI tool opens your browser to Knowi's login page.
3. Log in (if not already signed in) and click Allow on the consent page.
4. Done. The AI tool receives a long-lived token automatically and stores it - no repeated auth until the token expires (1 year).

Under the hood, this uses OAuth 2.1 with PKCE:

• The AI tool discovers Knowi's OAuth endpoints via GET /.well-known/oauth-authorization-server
• Authorization uses response_type=code with code_challenge_method=S256
• The token endpoint exchanges the code + PKCE verifier for a 1-year MCP bearer token
• No client secret needed - security comes from PKCE

See each client's setup guide for the exact configuration.

Option 2: MCP Token (Manual)

If your MCP client doesn't support OAuth, or you prefer manual token management, generate a long-lived MCP token from the Knowi UI.

1. Log into Knowi.
2. Navigate to Settings > AI Settings.
3. Under MCP Token, select an expiry period and click Generate Token.
4. Copy the token and paste it into your AI tool's configuration.

Use the token as a Bearer token in all MCP requests:

Authorization: Bearer YOUR_MCP_TOKEN

Security: The MCP token is a separate, revocable credential scoped to MCP endpoints only - it cannot access the broader Management API. Generating a new token automatically revokes any previous one. Revoke at any time from AI Settings.

Option 3: Standard Bearer Token

For short-lived programmatic access, use the standard Management API login:

POST /api/2.0/login

curl -X POST https://www.knowi.com/api/2.0/login \
  -H "Content-Type: application/json" \
  -d '{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}'

This returns a bearer token that expires after 1 hour. Request a new token when you receive a 401 response.

Instance URL: While the examples here use https://www.knowi.com, 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)

Endpoints

All MCP endpoints are at /api/2.0/mcp/.

Health Check

curl https://www.knowi.com/api/2.0/mcp/health

Response:

{
  "status": "healthy",
  "toolCount": 31,
  "tools": ["knowi_do", "knowi_ask", "knowi_search", ...],
  "activeSessions": 0
}

List Tools

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://www.knowi.com/api/2.0/mcp/tools

Returns an array of tool definitions with name, description, and input schema for each tool.

Call a Tool

Request

POST /api/2.0/mcp/tools/call

curl -X POST https://www.knowi.com/api/2.0/mcp/tools/call \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "knowi_list_dashboards",
    "arguments": {}
  }'

Response

{
  "content": [
    {"type": "text", "text": "Found 3 dashboards"}
  ],
  "isError": false,
  "_meta": {
    "executionTimeMs": 245
  }
}

Available Tools

The MCP server exposes 31 tools: 3 AI-powered tools and 28 deterministic tools.

AI-Powered Tools

These tools use the AI orchestrator to interpret natural language and chain multiple operations together.

knowi_do

Execute any Knowi operation using natural language. The orchestrator routes the instruction to the appropriate internal agent(s).

Example:

{
  "name": "knowi_do",
  "arguments": {
    "instruction": "Create a sales dashboard with revenue trends and top products"
  }
}

Note: knowi_do blocks destructive operations (delete, remove, drop). Use knowi_delete for those.

knowi_ask

Ask a data question in natural language. The AI finds the relevant dataset, generates a query, executes it, and returns results.

Example:

{
  "name": "knowi_ask",
  "arguments": {
    "question": "What were total sales last quarter?",
    "datasetIds": [456]
  }
}

Response includes the executed query, result fields, data rows, and the datasets that were searched.

knowi_search

Search across all Knowi assets using keyword or semantic search.

Example:

{
  "name": "knowi_search",
  "arguments": {
    "query": "customer retention",
    "assetType": "dashboard"
  }
}

Deterministic Tools

These tools execute specific operations directly without AI interpretation. They are fast and predictable.

knowi_list_dashboards

List all dashboards accessible to the authenticated user. No required parameters.

{
  "name": "knowi_list_dashboards",
  "arguments": {}
}

Returns dashboard IDs, names, and widget counts.

knowi_get_data

Retrieve data from a widget or dataset.

*One of widgetId or datasetId is required.

knowi_get_details

Get full details for any asset.

Returns full metadata including schema (for datasets), widget counts (for dashboards), and configuration details.

knowi_find_widget

Find widgets by name, optionally scoped to a dashboard.

Returns matching widget IDs, names, chart types, and dataset information.

knowi_push_data

Push data rows to a dataset. Creates the dataset if it does not exist.

knowi_import_file

Import file data (CSV, JSON, XML, or Excel) into a Knowi dataset. Pass inline text for CSV/JSON/XML, or base64-encoded content for Excel. Creates or updates a dataset.

*One of content or fileUrl is required.

knowi_export_pdf

Export a dashboard or widget as a PDF. Returns base64-encoded PDF content.

*One of dashboardId or widgetId is required.

knowi_export_csv

Export a dashboard or widget as CSV. For dashboards, exports all widgets as separate CSV files. Returns base64-encoded content.

*One of dashboardId or widgetId is required.

knowi_get_embed_url

Generate an embeddable share URL for a dashboard or widget.

*One of dashboardId or widgetId is required.

knowi_create_widget

Create a visualization on a dataset. Use knowi_get_data with a small limit first to inspect field names - the widget will show no data if field names are wrong.

knowi_update_widget

Update an existing widget's data transformations (filters, aggregations, sorting) and/or display settings (chart type, name). Changes are saved server-side immediately.

knowi_layout_dashboard

Set widget positions and sizes on a dashboard. Grid is 24 columns wide.

knowi_create_datasource

Create a new datasource connection.

knowi_create_query

Create a query against a datasource.

knowi_run

Trigger execution of a query or report.

*One of queryId or reportId is required.

knowi_create_report

Create a scheduled report that sends a dashboard or widgets via Email, Slack, or Teams.

*One of dashboardId or widgetIds is required.

knowi_update_report

Update an existing scheduled report's configuration. Only specified fields are changed.

knowi_create_alert

Create an alert on a dataset. Supports conditional alerts (trigger when a C9QL condition matches), data-not-updated alerts, and query error alerts.

knowi_list_alerts

List alerts accessible to the current user. Optionally filter by dataset or widget.

knowi_test_alert

Test an alert by triggering it immediately. Sends notifications if the condition matches. Results are not recorded in the alert's history.

knowi_update_alert

Update an existing alert. Only specified fields are changed.

knowi_ingest_document

Ingest a document (PDF, Word, CSV, Excel, images, or text) into Knowi for Q&A and data extraction. Documents are chunked, embedded, and stored for semantic search.

*One of fileUrl or content is required.

knowi_ask_document

Ask a natural language question against ingested documents. Returns an AI-generated answer with source citations.

knowi_extract_document_data

Extract structured data from documents into a Knowi dataset. Define the fields to extract - Knowi parses each document and returns structured rows that can be queried and visualized.

knowi_list_documents

List documents ingested into the document store. Returns document names and IDs for use with ask/extract/delete tools.

knowi_delete_document

Delete an ingested document from the vector store. Requires confirmation.

knowi_get_insights

Generate AI-powered insights and recommendations for a widget or dashboard. Returns observations, trends, anomalies, and actionable recommendations.

*One of widgetId or dashboardId is required.

knowi_delete

Delete a Knowi asset. This is the only tool that performs destructive operations.

All three parameters are required. The confirm parameter must be explicitly set to true.

Streamable HTTP Transport

MCP-compatible clients (Claude Code, Claude Desktop, Cursor, etc.) connect using the Streamable HTTP transport. This uses a single POST endpoint for all operations - no persistent connection required.

How It Works

Every MCP operation is a standard HTTP request/response. The client sends a JSON-RPC message via POST, and the server returns the result immediately. If the server restarts (e.g., during an update), the client simply retries the next request - no reconnection needed.

Initialize

curl -X POST https://www.knowi.com/api/2.0/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}'

Response includes a Mcp-Session-Id header. Send this header on subsequent requests.

Mcp-Session-Id: sh-1

{"jsonrpc": "2.0", "id": 1, "result": {
  "protocolVersion": "2024-11-05",
  "capabilities": {"tools": {}},
  "serverInfo": {"name": "knowi-mcp-server", "version": "1.0.0"}
}}

Call a Tool

curl -X POST https://www.knowi.com/api/2.0/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: sh-1" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "knowi_list_dashboards",
      "arguments": {}
    }
  }'

JSON-RPC Methods

Session Management

• The server returns a Mcp-Session-Id header on every response
• The client sends this header on subsequent requests for session continuity
• Sessions auto-expire after 30 minutes of inactivity
• The client can explicitly terminate a session with DELETE /api/2.0/mcp (include the Mcp-Session-Id header)
• If the server restarts, old sessions expire - the client automatically gets a new session on the next request

Security

Authentication Flow

MCP Token (recommended for MCP clients):

1. The user generates an MCP token from Settings > AI Settings > MCP Token in the Knowi UI.
2. Knowi revokes any existing MCP token for the user and creates a new long-lived token (configurable: 30 days to 1 year).
3. The user copies the token into their MCP client configuration (e.g., Claude Code, Claude Desktop) as a Bearer token.
4. The ManagementInterceptor validates the token, verifies it is scoped to MCP endpoints, loads the associated user (including roles, permissions, and customer context), and establishes a security session for the request.
5. If the token is compromised, the user revokes it from AI Settings and generates a new one. No other credentials are affected.

Standard Bearer Token (for programmatic use):

1. The client sends a login request with clientId and clientSecret to POST /api/2.0/login.
2. Knowi returns a bearer token valid for 1 hour.
3. When the token expires, the client must obtain a new one.

All tokens are tied to a specific user and inherit that user's full permission set. Tokens grant the same access as the user logging in through the UI.

Authorization

Every tool checks that the authenticated user has access to the requested resource before executing:

• Dashboard and widget access: Validated using user.isAllowed(resourceId, assetType, write), the same authorization check used throughout Knowi's UI and API.
• Dataset access: Validated by matching the dataset's customer ID against the user's customer ID. A user cannot access datasets belonging to a different organization.
• Datasource access: Validated by customer ID ownership. Creating datasources scopes them to the authenticated user's organization.

Access denied errors are logged with user ID and the resource that was requested.

Data Flow and AI Provider Implications

Understanding what data is sent where is critical for security evaluation. When using the MCP server, there are two separate data flows:

Flow 1: Tool responses to the MCP client. Every tool - deterministic and AI-powered - returns results to the calling MCP client (e.g., Claude Code, Claude Desktop, Cursor). These results may contain actual data rows, dashboard metadata, field names, and generated insights. The client's LLM sees this data. For example, if you ask Claude Code to get data from a widget, the data rows are returned to Claude, which runs on Anthropic's infrastructure. This is inherent to MCP - the client must receive the results to act on them.

Flow 2: Knowi's internal AI processing. AI-powered tools (knowi_do, knowi_ask, knowi_search) additionally send data to Knowi's configured AI model for reasoning (SQL generation, chart type selection, etc.). Where this data goes depends on the configured provider:

• Knowi Internal: Data stays within Knowi's infrastructure for AI processing.
• OpenAI / Anthropic: Data is also sent to the external provider's API.

See AI Model Providers to configure which provider Knowi uses internally.

Deterministic tools (knowi_list_dashboards, knowi_get_data, knowi_push_data, etc.) do not invoke any AI model on Knowi's side - they execute directly against Knowi's services. However, their results are still returned to the MCP client.

What the AI model on Knowi's side receives (Flow 2 only):

Security implication: Even if Knowi is configured with its internal AI provider, using the MCP server means data flows to the MCP client's infrastructure. Evaluate whether the data accessible through your Management API credentials is appropriate for transmission to the client platform you are using. For maximum data isolation, use Knowi's in-product agents (Dashboard and Widget AI Assistants) instead of MCP.

Input Validation and Prompt Injection

All inputs to AI-powered tools are validated before execution:

Tool name whitelisting: Only the 15 registered tool names are accepted. Any other tool name returns a 404 error.

Instruction length limit: Natural language instructions are capped at 2,000 characters.

Prompt injection detection: Instructions are scanned against patterns known to indicate prompt injection attempts, including:

• "ignore previous instructions"
• "system prompt"
• "you are now" / "act as" / "pretend"
• "disregard" / "override" / "forget"
• "reveal the/your/system"
• "jailbreak" / "DAN"

Matching instructions are rejected with an error before reaching the AI model.

Input sanitization: Control characters (ASCII 0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F, 0x7F) are stripped from all string arguments.

Destructive Operation Safeguards

The knowi_do tool scans instructions for destructive intent (delete, remove, drop, destroy, purge, wipe). If detected, the request is blocked and the user is directed to use the explicit knowi_delete tool instead.

The knowi_delete tool requires three explicit parameters - assetType, assetId, and confirm: true - preventing accidental or AI-hallucinated deletions. All three parameters must be provided; omitting any one causes the request to fail.

Session Security

Streamable HTTP sessions are bound to the authenticated user. Each session receives a unique Mcp-Session-Id and validates that subsequent requests come from the same user who created the session. A valid bearer token is required for every request - session IDs alone do not grant access.

Sessions auto-expire after 30 minutes of inactivity and can be explicitly terminated by the client.

Audit Logging

All agent executions are logged with:

• The user's input prompt
• Success or failure status
• Agent response
• Execution time in milliseconds
• Associated resource IDs (dashboard, widget, dataset)

MCP tool calls are logged with the tool name, success status, and execution time. Logs are available to account administrators.

Data Exposure Controls

Data returned by tools is truncated by default:

• knowi_get_data returns a maximum of 100 rows by default (configurable via the limit parameter).
• knowi_ask returns a maximum of 100 rows.
• AI-powered recommendations truncate data to fit the AI model's context window, iteratively reducing rows until the prompt fits.

The response includes totalRows and returnedRows counts so the caller knows if data was truncated.

Known Limitations

• No per-user rate limiting: The MCP server does not enforce per-user rate limits on tool calls. Rate limiting should be applied at the network layer (e.g., API gateway, reverse proxy) for production deployments.
• Token scoping: Bearer tokens inherit the user's full permission set. There is no mechanism to create a token scoped to specific tools or read-only access.
• One MCP token per user: Registering a new MCP token revokes the previous one. A user cannot have multiple active MCP tokens simultaneously.

Error Handling

Errors are returned in the MCP response format:

{
  "content": [
    {"type": "text", "text": "Access denied: you do not have permission to access dashboard 12345"}
  ],
  "isError": true
}

Common error scenarios:

Rate Limits

AI-powered tools (knowi_do, knowi_ask, knowi_search) consume agent calls, which are metered based on your plan. Deterministic tools are unlimited.

See your account settings for current usage and limits.