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

Knowi App development is available when Apps is enabled for the account and the signed-in user's role permits it. The consent page discloses that App changes may write commits to a repository already authorized by the customer in Knowi.

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.

Manual MCP tokens use the same account, role, and App permissions as OAuth tokens.

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.

Standard bearer tokens use the same account, role, and App permissions when calling MCP tools.

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": ["do", "ask", "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": "list_dashboards",
    "arguments": {}
  }'

Response

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

Available Tools

The MCP server exposes both AI-powered and deterministic tools.

Knowi App development

knowi_app is one context-efficient tool for Knowi Apps. Its explicit name and schema keep it separate from unrelated software projects in Claude, Codex, or another MCP client.

MCP is the recommended way to build Knowi Apps. For a complete conversation from setup to a published App, follow Build through MCP. The Apps MCP action reference covers tool fields and permissions.

Builds are asynchronous: call read, write the code in your assistant, submit change, then poll status when done is false. MCP does not invoke Knowi's AI generator. Call preview separately when requested. Call setup first to discover authorized repositories and whether you can create one. Set optional source to an exact repository label returned by setup, or omit it when only one writable repository is available. If none is available, use the repository creation options below when permitted, or ask a Knowi administrator to make one available.

App history records observed commits, builds, and publishes across Claude, Codex, and other MCP clients. Open the App in Knowi and use Commits > Refresh to load changes made by another client. The commit list shows repository commit messages and Git authors; Versions brings together each build and its publication details. Recorded authenticated requesters and publishers are identified separately from Git authors. Refresh preserves your unsent Builder request, selected data, and running preview.

Optional intent and handoff notes are limited to 2,000 characters each, shared with App collaborators, and attached to the resulting commit. They appear in version details, and read identifies notes from earlier commits as stale. Keep private chats and secrets out of these shared notes. Client names, when available, are advisory attribution; the authenticated Knowi user determines permissions. Private conversations in Knowi are separate, and external chat transcripts are not automatically imported.

An App uses the dashboards and datasets selected for it. Describe the data you want so the assistant can find authorized assets and declare their bindings in the app.json file submitted with change. Knowi checks the editor's access for preview and the publisher's access at publication. Live Knowi sign-in Apps apply each viewer's data permissions. Public and App-managed Apps can expose selected dataset results through a grant checked against the publisher's current access and content filters; individual visitors have no Knowi identity. See App access and security.

create can also use repository: "knowi_managed" or repository: "ssh" with remoteUrl; SSH setup returns a deploy key to authorize before retrying with the source. create and change support access and managed-database settings. Publishing requires apps:publish; editing requires apps:edit and the App ACL. Knowi verifies the active connection, account, repository authorization, and action permissions on every call. The tool cannot delete an App, upload built output, or expose repository credentials. A Git host outage blocks new changes and builds but does not stop an already published App version.

After publish, use the returned App ID and declared page paths with create_report or create_alert. For example, an agent can build and publish an operations review, then create a Monday email report for its Overview page. Core owns schedules, recipients, and delivery; the App does not need a scheduler. Calling these MCP tools while building an App is separate from the App's runtime report.send and report.schedule capabilities.

AI-Powered Tools

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

do

Execute a Knowi operation using natural language. Knowi routes the instruction to the appropriate capability.

Example:

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

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

ask

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

Example:

{
  "name": "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.

search

Search across all Knowi assets using keyword or semantic search.

Example:

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

Deterministic Tools

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

list_dashboards

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

{
  "name": "list_dashboards",
  "arguments": {}
}

Returns dashboard IDs, names, and widget counts.

get_data

Retrieve data from a widget or dataset.

*One of widgetId or datasetId is required.

get_details

Get full details for any asset.

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

find_widget

Find widgets by name, optionally scoped to a dashboard.

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

push_data

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

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.

export_pdf

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

*One of dashboardId or widgetId is required.

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.

get_embed_url

Generate an embeddable share URL for a dashboard or widget.

*One of dashboardId or widgetId is required.

create_widget

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

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.

create_dashboard

Create a new dashboard, optionally with existing widgets on it. To build a dashboard from scratch, create it here, then call create_widget with the returned dashboardId. If the name is already taken, a number is appended.

layout_dashboard

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

update_dashboard

Rename a dashboard, change its description, or change settings from its Settings panel. An unknown setting name is rejected with the list of valid ones. Custom CSS/JS, header and footer code can't be changed through MCP.

update_dashboard_filters

Set dashboard-level filters, which apply to every widget on the dashboard that has the field. Each filter replaces the existing dashboard filter on the same field; other filters are kept unless replaceAll is true. Locked filters can't be changed.

create_datasource

Create a new datasource connection.

create_query

Create a query against a datasource and run it to populate a dataset. Each run replaces the dataset (replace_all) unless overwriteStrategy says otherwise. The query runs once unless frequency and frequencyType schedule it.

*One of datasourceId or datasourceName is required.

update_query

Update an existing query: rename it, change its query text, set its overwrite strategy or schedule, or run it now. Only the fields passed change. Requires write access to the query.

get_details with assetType='query' returns the current overwriteStrategy, overwriteKeys, scheduled and schedule so you can confirm what was set.

cloud9ql_assist

Generate, fix, explain, convert, validate, or preview Cloud9QL using your dataset's actual schema and sample rows. Every query the tool returns has been executed against the dataset to confirm it parses and produces output - the response includes a validity flag and a small preview so you know the query works before applying it. Repairs broken Cloud9QL automatically (up to 2 retries) using validator hints. See the Cloud9QL Assistant docs for the in-product equivalent.

*One of dataset_id or dataset_hint is required.

Requires the AI_USE_AGENT_ASSISTANT_QUERIES, QUERY_EDIT, and QUERY_CREATE permissions on the calling user's role.

run

Trigger execution of a query or report.

*One of queryId or reportId is required.

create_report

Create a scheduled report that sends a dashboard or widgets via Email, Slack, or Teams. An App schedules reports for its own pages through the report.send and report.schedule capabilities, not through this tool.

*One of dashboardId or widgetIds is required.

Example weekly report:

{
  "name": "create_report",
  "arguments": {
    "dashboardId": 42,
    "recipients": "leads@example.com",
    "reportName": "Weekly operations review",
    "frequencyType": "weeks",
    "frequency": 1,
    "dayOfWeek": "MONDAY",
    "startTime": "08:00",
    "timezone": "America/Los_Angeles"
  }
}

update_report

Update an existing scheduled report's configuration, or pause or resume it. Only specified fields are changed.

create_alert

Current result comparison does not provide per-incident delivery tracking, and data attachments remain CSV.

list_alerts

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

test_alert

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

update_alert

Update an existing alert. Only specified fields are changed.

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.

ask_document

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

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.

list_documents

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

delete_document

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

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.

explain_lineage

Explain how a Knowi widget, dataset, query, or dashboard is built and what depends on it. Returns the same lineage recipe surfaced in the Data Lineage drawer: upstream sources, transformations, field traces, downstream impact, and any permission redactions.

*Either assetType + assetId, or one of the shortcut ID params (widgetId/datasetId/queryId/dashboardId), is required.

Example:

{
  "name": "explain_lineage",
  "arguments": {
    "widgetId": 12345,
    "mode": "build",
    "includeFields": true
  }
}

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.

Semantic Layer Tools

These tools read and manage the Semantic Layer - the business glossary, dataset-level semantics, and how questions resolve against them - programmatically. Editing is subject to the same permissions as the Semantic workspace: Admin for glossary terms, Semantic edit access for dataset semantics.

list_glossary_terms

List the business glossary terms defined for the account. Each term includes its name, definition, aliases, status (Draft or Published), and how many datasets/fields it is mapped to.

get_glossary_term

Get one business glossary term: its full definition, aliases, and dataset/field mappings.

define_term

Create or update a business glossary term. The term is saved as a Draft - use publish_term to publish it.

Example:

{
  "name": "define_term",
  "arguments": {
    "name": "Customer",
    "definition": "A company or individual with at least one paid order.",
    "aliases": ["Client", "Buyer"]
  }
}

map_term

Map a business glossary term to a dataset, optionally narrowing to specific fields. Existing mappings are preserved; the new mapping is added.

publish_term

Publish a Draft business glossary term so it participates in semantic resolution. Publishing is an explicit decision - terms are never published automatically.

update_dataset_semantics

Set dataset-level semantics: field synonyms, the primary date field used for date questions, and dataset AI instructions. Omitted settings are left unchanged; pass an empty value to clear a setting.

get_semantic_context

Resolve a natural-language question against the semantic layer without running any query. Returns matched business terms, the resolved assets (primary and alternatives) with certification state, the resolution decision (REUSE, ADAPT, or CREATE), the execution disposition (continue, clarify, or block), and any blockers. Use ask to actually execute.

explain_semantic_resolution

Explain how the semantic layer would resolve a question, without running any query: the candidates considered with relevance scores, why the primary asset was selected, and why alternatives were not (lower relevance, not certified, and so on).

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": "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. Knowi validates the token, confirms that it is scoped to MCP endpoints, and establishes the associated user and permissions 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 applies the authenticated user's current account and resource permissions. Requests for another organization or an unauthorized asset are denied. Resources created through MCP belong to the authenticated user's organization.

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 AI processing. AI-powered tools (do, ask, 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 In-House AI: 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 the provider Knowi uses.

Deterministic tools (list_dashboards, get_data, 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: Using the MCP server means data flows to the MCP client's infrastructure. Evaluate whether the data accessible through your MCP token 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

Only registered tools are accepted. AI-powered inputs are length-limited, normalized, and screened before model execution. These checks do not replace authorization; Knowi applies the user's permissions independently on every request.

Destructive Operation Safeguards

The 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 delete tool instead.

The 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:

• get_data returns a maximum of 100 rows by default (configurable via the limit parameter).
• 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

• Usage limits: Usage and capacity limits may apply. Contact your Knowi administrator or account representative for your account's limits.
• Token permissions: Every tool inherits the authenticated user's current account, role, and asset permissions.
• 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 (do, ask, search) consume agent calls, which are metered based on your plan. Deterministic tools are unlimited.

See your account settings for current usage and limits.