Claude Code + AgenticBI Setup

Connect Claude Code or Claude Desktop to AgenticBI'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
  • AgenticBI account with AI Agents enabled

Option A: OAuth Browser Auth (Recommended)

The easiest way to connect - no token copy/paste needed. Claude opens your browser, you log into AgenticBI, and you're connected.

Claude Code (CLI)

  1. Run the following command:

    claude mcp add agenticbi --transport http https://app.agenticbi.com/api/2.0/mcp
    
  2. Exit Claude (Ctrl+C), then reopen it on the command line.

  3. Run /mcp, select agenticbi, and click Enable, then Authenticate. This opens your browser and prompts you to log in.

Claude Desktop

  1. Go to Settings > Connectors and click Add Custom Connector.
  2. Enter a name for the connector (e.g., agenticbi).
  3. Enter https://app.agenticbi.com/api/2.0/mcp as the Remote Server MCP URL.
  4. Click Connect. This opens a browser tab and prompts you to log in.

Option B: Manual Token

If you prefer to manage the token manually, or if OAuth doesn't work in your environment:

Step 1: Generate an MCP Token

  1. Log into AgenticBI.
  2. Navigate to Settings > AI Settings.
  3. Under MCP Token, select a token expiry (30 days to 1 year) and click Generate Token.

Step 2: Configure Claude

Claude Code (CLI):

claude mcp add agenticbi https://app.agenticbi.com/api/2.0/mcp --transport http --header "Authorization: Bearer YOUR_MCP_TOKEN"

Claude Code (via config file): Add to ~/.claude/settings.json:

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

Claude Desktop: Edit your config file (paths above) with the same JSON, replacing YOUR_MCP_TOKEN.

Instance URL: https://app.agenticbi.com

Verify

Restart Claude Code (or Claude Desktop) and ask:

"What AgenticBI tools are available?"

You should see 15 tools including do, ask, search, list_dashboards, and others.

Usage Examples

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

List Dashboards

"Show me my AgenticBI dashboards"

Ask a Data Question

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

Create a Dashboard

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

Search for Assets

"Search AgenticBI for dashboards related to customer analytics"

Get Data from a Widget

"Get the data from AgenticBI widget 12345"

Export to PDF

"Export AgenticBI dashboard 67890 to PDF"

Create a Datasource

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

Push Data

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

Available Tools

Once connected, Claude has access to 15 AgenticBI tools:

AI-Powered (natural language):

  • do - Execute any AgenticBI operation via natural language
  • ask - Ask data questions in natural language
  • search - Search across all AgenticBI assets

Deterministic (direct operations):

  • list_dashboards - List all accessible dashboards
  • get_data - Retrieve data from a widget or dataset
  • push_data - Push data rows to a dataset
  • screenshot - Generate screenshot URL for a dashboard or widget
  • export_pdf - Export dashboard or widget as PDF
  • get_embed_url - Generate embeddable share URL
  • delete - Delete an asset (requires confirmation)
  • run - Trigger query or report execution
  • get_details - Get full details for any asset
  • create_datasource - Create a new datasource connection
  • create_query - Create a query against a datasource
  • 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 AgenticBI
claude mcp add agenticbi https://app.agenticbi.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 AgenticBI entirely:

claude mcp remove AgenticBI

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

Troubleshooting

"AgenticBI tools not found"

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

    curl https://app.agenticbi.com/api/2.0/mcp/health
    
  3. Verify your MCP token is valid:

    curl -H "Authorization: Bearer YOUR_MCP_TOKEN" \
      https://app.agenticbi.com/api/2.0/mcp/tools
    

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

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

    claude mcp remove AgenticBI
    claude mcp add agenticbi https://app.agenticbi.com/api/2.0/mcp --transport http --header "Authorization: Bearer YOUR_MCP_TOKEN"
    
  2. Verify the AgenticBI instance is reachable: curl https://app.agenticbi.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 AgenticBI instance.
  2. Check that your AgenticBI 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 AgenticBI 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 AgenticBI 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 AgenticBI 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 AgenticBI uses internally.

Specifics:

  • Deterministic tools (list dashboards, get data, export, etc.) return data directly from AgenticBI to Claude. Data rows are capped at 100 by default.
  • AI-powered tools (do, ask, search) first invoke AgenticBI's AI orchestrator (which may process data through AgenticBI'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 AgenticBI UI.

Network Security

All connections to AgenticBI should use HTTPS in production. If your AgenticBI 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.