MCP Server

Connect Claude Code, Claude Desktop, or Cursor to your Definite data using the Model Context Protocol (MCP). Query databases, manage integrations, build dashboards, and work with semantic models directly from your AI assistant.

Prerequisites: You’ll need a Definite API key. Find yours in the bottom left user menu of the Definite app, or see the Definite API docs for details.

Quick Start

Claude Code CLI

claude mcp add definite \
  --transport http \
  https://api.definite.app/v3/mcp/http \
  --header "Authorization: YOUR_API_KEY"

Verify the connection:

claude mcp list

Claude Desktop

Add to your config file:

macOS: ~/.config/claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "definite": {
      "transport": "http",
      "url": "https://api.definite.app/v3/mcp/http",
      "headers": {
        "Authorization": "YOUR_API_KEY"
      }
    }
  }
}

Save and restart Claude Desktop.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "definite": {
      "transport": "http",
      "url": "https://api.definite.app/v3/mcp/http",
      "headers": {
        "Authorization": "YOUR_API_KEY"
      }
    }
  }
}

Available Tools

Query

Tool	Description
`run_sql_query`	Execute SQL queries against DuckLake. Supports DDL, DML, and SELECT. Optional `integration_id` to target a specific integration.
`run_cube_query`	Execute a semantic Cube query with measures, dimensions, timeDimensions, filters, order, and limit. Optional `integration_id` and `raw` parameters.

Semantic Layer

Tool	Description
`search_cube_schema`	Discover cubes, dimensions, and measures. Supports case-insensitive search, filtering by cube name, and configurable result limit (default 50, max 200).
`list_cube_models`	List all Cube model YAML files for a given integration. Returns file names, cube names, and metadata.
`get_cube_model`	Get a specific Cube model YAML file’s full content.
`save_cube_model`	Save a Cube model YAML file. Validates YAML syntax and Cube schema before saving.
`delete_cube_model`	Delete a Cube model YAML file.

Integrations

Tool	Description
`collect_secrets`	Collect credentials securely via a hosted form. Pass `integration_type` (e.g., postgres, snowflake, stripe) and it auto-determines the correct fields. Returns a `credential_session_id`.
`oauth_connect`	Initiate an OAuth flow for supported integrations (HubSpot, Salesforce, Google Sheets, QuickBooks, LinkedIn Ads, Facebook, Intercom, Notion, Slack). Returns a `credential_session_id`.
`check_credential_session`	Poll the status of a credential session created by `collect_secrets` or `oauth_connect`. When status is `submitted`, pass the `credential_session_id` to `create_integration`.
`create_integration`	Create a new integration with collected credentials. Call after `check_credential_session` returns `submitted`. Validates the connection before creation.
`list_integrations`	List integrations for the team. Filter by `integration_type` (e.g., ducklake, postgres). Returns id, name, type, sync status, and validation status.
`get_integration`	Get full details of a specific integration by UUID. Returns type, name, validation status, sync configuration, credentials metadata, and timestamps.
`get_database_schema`	Get available schemas and tables from a database integration. Use before `configure_sync` to discover syncable tables. Optional `schema_filter`.

Syncs

Tool	Description
`configure_sync`	Configure a data sync from a source integration to DuckLake. Supports table selection, scheduling (presets or cron), and load methods (merge/append/overwrite).
`list_sync_runs`	List recent sync runs for a data source integration. Returns run status (SUCCESS, FAILED, STARTED), runtime, timestamps, and identifiers (`dag_name`, `run_id`) needed for `get_sync_logs`. Optional `limit` (default 10) and `status_filter`.
`get_sync_logs`	Get log output from a specific sync run. Requires `integration_id`, `dag_name`, and `run_id` from `list_sync_runs`. Supports three modes: `summary` (first/last lines + errors), `errors` (only error/warning lines), and `full` (complete logs, truncated at 100KB).

Docs

Tool	Description
`list_docs`	List docs (dashboards, reports, pipelines) for the team. Filter by `name_search`, `project_id`, `pinned_only`, or `include_archived`.
`get_doc`	Get a doc by UUID. Returns full metadata, raw YAML content, and parsed YAML structure.
`create_doc`	Create a new doc. Requires `name` and `raw_yaml`. Optional: description, slug, project_id, is_pinned, is_public.
`update_doc`	Update an existing doc’s content or settings.
`delete_doc`	Soft-delete (archive) a doc by UUID.
`get_doc_schema`	Get the doc.yaml schema specification. Returns a human-readable reference with field descriptions, dataset types, tile configuration options, and YAML examples.
`execute_doc`	Execute datasets in a doc. Respects dependency ordering for pipelines. Supports `invalidate`, `persist`, and `async` (queue durable background execution).
`get_doc_execution_status`	Get status of an async `execute_doc` run. Returns durable run/attempt status, per-step summaries, and any DuckDB job metadata. Requires the `run_id` from `execute_doc`.
`get_doc_execution_logs`	Fetch logs for an async `execute_doc` run. Returns automation logs, Python execution logs, and DuckDB job diagnostics. Can scope to a specific `dataset_name`.
`update_doc_dataset`	Update a single dataset within a doc without replacing the full YAML.
`capture_doc_image`	Capture a doc or dashboard as a JPEG screenshot.

Drive

Tool	Description
`list_drive_files`	List files in the team’s Definite Drive. Supports prefix filtering and limit (max 1000).
`get_drive_download_url`	Get a signed URL for downloading a file from Drive. URL is valid for 1 hour.
`get_drive_upload_url`	Get a signed URL for uploading a file to Drive. URL is valid for 48 hours.
`read_drive_file`	Read a text file directly from Drive.
`write_drive_file`	Write a text file directly to Drive.
`create_drive_folder`	Create a folder in Drive.
`delete_drive_file`	Delete a file from Drive.

Onboarding Workflow

Step 1: Add Integrations

OAuth Integrations (use oauth_connect): Salesforce, QuickBooks, Intercom, Facebook Ads, Instagram, Slack, Notion, Google Analytics, Google Search Console, Google Sheets, Excel, SharePoint, LinkedIn Pages, Amazon Advertising, Amazon Selling Partner, Zoho CRM Credential Integrations (use collect_secrets → create_integration):

Integration	Required Fields
Postgres	host, port, database, username, password
MySQL	host, port, database, username, password
BigQuery	project_id, credentials_json
Snowflake	account, username, password, warehouse, database
Stripe	account_id, client_secret
HubSpot	access_token
Shopify	access_token, store

Step 2: Configure Data Sync

After connecting a source, sync data to DuckLake:

Find your DuckLake destination with list_integrations
Explore source schema with get_database_schema
Configure sync with configure_sync

Schedule options: hourly, every_4_hours, every_6_hours, every_12_hours, daily, weekly Load methods:

merge (recommended): Upsert based on primary key
append: Add new rows only
overwrite: Replace entire table

Step 3: Build Semantic Models

Create Cube models for business metrics:

List existing models with list_cube_models
Get a model for reference with get_cube_model
Save new models with save_cube_model
Search the schema with search_cube_schema

Step 4: Create Dashboards

Build docs (dashboards, reports) using YAML:

Get the schema spec with get_doc_schema
Create docs with create_doc
Update with update_doc

Troubleshooting

Connection fails

Verify your API key is valid and not expired
Check that you have the correct permissions
Ensure you’re using HTTP transport (recommended)

Session errors The connection may have timed out. Restart your MCP client to reconnect. Remove the server

claude mcp remove definite

Next Steps

See the Agent Reference for in-depth guides on querying data, building dashboards, automating Python pipelines, using the Definite SDK, and sending Slack/email alerts.

Support

For issues or questions, contact hello@definite.app or visit docs.definite.app.

Home

Getting Started

Analyze & Build

Pushing to Destinations

Extracting from Data Sources

Data Modeling

Definite API

Custom Python Functions

Workspace

Quick Start

Claude Code CLI

Claude Desktop

Cursor

Available Tools

Query

Semantic Layer

Integrations

Syncs

Docs

Drive

Onboarding Workflow

Step 1: Add Integrations

Step 2: Configure Data Sync

Step 3: Build Semantic Models

Step 4: Create Dashboards

Troubleshooting

Next Steps

Support

Home

Getting Started

Analyze & Build

Pushing to Destinations

Extracting from Data Sources

Data Modeling

Definite API

Custom Python Functions

Workspace

​Quick Start

​Claude Code CLI

​Claude Desktop

​Cursor

​Available Tools

​Query

​Semantic Layer

​Integrations

​Syncs

​Docs

​Drive

​Onboarding Workflow

​Step 1: Add Integrations

​Step 2: Configure Data Sync

​Step 3: Build Semantic Models

​Step 4: Create Dashboards

​Troubleshooting

​Next Steps

​Support

Quick Start

Claude Code CLI

Claude Desktop

Cursor

Available Tools

Query

Semantic Layer

Integrations

Syncs

Docs

Drive

Onboarding Workflow

Step 1: Add Integrations

Step 2: Configure Data Sync

Step 3: Build Semantic Models

Step 4: Create Dashboards

Troubleshooting

Next Steps

Support