Claude Code + Knowi Setup

Connect Claude Code or Claude Desktop to Knowi's MCP server. Once connected, you can create dashboards, query data, export results, and manage reports using natural language ? directly from your AI assistant.

Prerequisites

  • Claude Code (CLI) or Claude Desktop installed
  • Knowi account with AI Agents enabled

Step 1: Generate an MCP Token

  1. Log into Knowi.
  2. Navigate to Settings > AI Settings.
  3. Under MCP Token, select a token expiry (30 days to 1 year) and click Generate Token.
  4. Copy the token immediately ? it is shown only once.

The page also shows the Claude Code configuration snippet. Copy that too.

Step 2: Configure Claude

Claude Code (CLI)

Run this command, replacing YOUR_MCP_TOKEN with the token from Step 1:

claude mcp add knowi https://your-instance.knowi.com/api/2.0/mcp --transport http --header "Authorization: Bearer YOUR_MCP_TOKEN"

Claude Desktop

Edit your config file:

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

{
  "mcpServers": {
    "knowi": {
      "type": "streamable-http",
      "url": "https://your-instance.knowi.com/api/2.0/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Claude Code (via config file)

Add to ~/.claude/settings.json (or project-level .claude/settings.json):

{
  "mcpServers": {
    "knowi": {
      "type": "streamable-http",
      "url": "https://your-instance.knowi.com/api/2.0/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Step 3: Verify

Restart Claude Code (or Claude Desktop) and ask:

"What Knowi tools are available?"

You should see 15 tools including knowi_do, knowi_ask, knowi_search, knowi_list_dashboards, and others.

Usage Examples

Once connected, interact with Knowi using natural language from Claude.

List Dashboards

"Show me my Knowi dashboards"

Ask a Data Question

"Ask Knowi: what were our top customers by revenue last month?"

Create a Dashboard

"Use Knowi to create a sales dashboard with revenue trends and top products"

Search for Assets

"Search Knowi for dashboards related to customer analytics"

Get Data from a Widget

"Get the data from Knowi widget 12345"

Export to PDF

"Export Knowi dashboard 67890 to PDF"

Create a Datasource

"Create a MySQL datasource in Knowi called 'Production DB' at db.example.com:3306"

Push Data

"Push these sales records to a Knowi dataset called 'Daily Sales'"

Available Tools

Once connected, Claude has access to 15 Knowi tools:

AI-Powered (natural language):

  • knowi_do ? Execute any Knowi operation via natural language
  • knowi_ask ? Ask data questions in natural language
  • knowi_search ? Search across all Knowi assets

Deterministic (direct operations):

  • knowi_list_dashboards ? List all accessible dashboards
  • knowi_get_data ? Retrieve data from a widget or dataset
  • knowi_push_data ? Push data rows to a dataset
  • knowi_screenshot ? Generate screenshot URL for a dashboard or widget
  • knowi_export_pdf ? Export dashboard or widget as PDF
  • knowi_get_embed_url ? Generate embeddable share URL
  • knowi_delete ? Delete an asset (requires confirmation)
  • knowi_run ? Trigger query or report execution
  • knowi_get_details ? Get full details for any asset
  • knowi_create_datasource ? Create a new datasource connection
  • knowi_create_query ? Create a query against a datasource
  • knowi_find_widget ? Find widgets by name

For complete tool documentation, see MCP Server.

Token Management

Revoking a Token

If your token is compromised or you want to rotate it:

  1. Go to Settings > AI Settings > MCP Token.
  2. Click Revoke Token.
  3. Generate a new token and update your Claude configuration (see below).

Generating a new token also automatically revokes any previous token.

Token Expiry

When a token expires, Claude will receive 401 errors. Generate a new token from AI Settings and update your Claude configuration.

Updating Your Claude Code Configuration

When you generate a new token (after revoking or expiring), you must remove and re-add the MCP server in Claude Code:

claude mcp remove knowi
claude mcp add knowi https://your-instance.knowi.com/api/2.0/mcp --transport http --header "Authorization: Bearer YOUR_NEW_TOKEN"

Then restart Claude Code for the change to take effect.

For Claude Desktop, edit your config file and replace the old token with the new one, then restart Claude Desktop.

Removing the MCP Connection

To disconnect Claude from Knowi entirely:

claude mcp remove knowi

For Claude Desktop, remove the "knowi" entry from your config file.

Troubleshooting

"Knowi tools not found"

  1. Restart Claude Code or Claude Desktop completely.
  2. Check the health endpoint to verify Knowi's MCP server is running:

    curl https://your-instance.knowi.com/api/2.0/mcp/health
    
  3. Verify your MCP token is valid:

    curl -H "Authorization: Bearer YOUR_MCP_TOKEN" \
      https://your-instance.knowi.com/api/2.0/mcp/tools
    

"Failed to connect" (X next to knowi in `claude mcp list`)

  1. Make sure you used --transport http. If you used the wrong transport, remove and re-add:

    claude mcp remove knowi
    claude mcp add knowi https://your-instance.knowi.com/api/2.0/mcp --transport http --header "Authorization: Bearer YOUR_MCP_TOKEN"
    
  2. Verify the Knowi instance is reachable: curl https://your-instance.knowi.com/api/2.0/mcp/health

  3. Restart Claude Code after making changes.

"Authentication failed" or 401 errors

  1. Your MCP token may have been revoked or expired. Generate a new one from AI Settings and update your config (remove and re-add).
  2. If using a self-hosted instance, check that the instance URL is reachable from your machine.

"Tool calls return errors"

  1. Verify the user has appropriate permissions for the requested resources.
  2. For dashboard or widget operations, ensure the user has access to those resources.
  3. Check that AI Agents is enabled for the account (Settings > AI Settings > AI Agents Access).

"Connection timeout"

  1. If behind a corporate firewall, check with your network team that outbound HTTPS connections are allowed to your Knowi instance.
  2. Check that your Knowi instance allows connections on the standard HTTP/HTTPS ports.

Security

Token Security

The MCP token is a revocable, scoped credential. It can only access MCP endpoints ? it cannot be used against the broader Management API. If a token is compromised:

  1. Revoke it immediately from AI Settings.
  2. Generate a new one.
  3. No other credentials are affected.

Do not commit Claude configuration files containing tokens to version control.

Access and Permissions

The MCP connection inherits the permissions of the user who generated the token. Claude can access and modify any dashboard, widget, or dataset that user can access through the Knowi UI.

For production use, consider creating a dedicated user with only the permissions needed. Avoid using admin credentials.

What Data Does Claude See?

When Claude calls any Knowi MCP tool, the tool response ? including data rows, field names, dashboard metadata, and generated insights ? is returned to Claude. Claude runs on Anthropic's infrastructure, so your Knowi data is transmitted to Anthropic's servers as part of normal tool use. This is true for all 15 tools, regardless of which AI provider Knowi uses internally.

Specifics:

  • Deterministic tools (list dashboards, get data, export, etc.) return data directly from Knowi to Claude. Data rows are capped at 100 by default.
  • AI-powered tools (knowi_do, knowi_ask, knowi_search) first invoke Knowi's AI orchestrator (which may process data through Knowi's configured AI model), then return results to Claude.

Consider what data is accessible to the user whose token you configure. The MCP connection gives Claude the same data access as that user in the Knowi UI.

Network Security

All connections to Knowi should use HTTPS in production. If your Knowi instance is behind a VPN or firewall, ensure the machine running Claude Code has network access to the instance URL.

For full details on the MCP server's security model, including authorization checks, prompt injection protection, and audit logging, see MCP Server Security.