Honeydew Semantic Layer MCP Server

official

Honeydew semantic layer provides a governed, business-friendly data model that unifies metrics, dimensions, and relationships across sources, enabling consistent self-service analytics and AI-powered data access

View on honeydew.ai

Documentation

MCP Server

What is MCP?

Model Context Protocol (MCP) is an open-source standard for securely connecting AI applications to external systems and tools. Honeydew provides an MCP server that connects your AI coding assistant to the Honeydew Semantic Layer.

When to use

Discover and explore your warehouse tables, schemas, and semantic model definitions
Build and maintain your semantic model through natural conversation
Query your data with natural language from any MCP-compatible assistant

Installation

Server URL

Honeydew exposes the MCP Server API at https://mcp.honeydew.cloud/mcp

If your organization uses a custom Honeydew hostname, replace the default URL with your tenant hostname. You can find the hostname in the Honeydew UI under **Settings > MCP Server**.

Authentication

There are two ways to authenticate with the Honeydew MCP Server: OAuth or HTTP Basic authentication.

OAuth Authentication (recommended)

Most clients support OAuth authentication. When you first connect, you'll be prompted to:

Log in with your Honeydew account
Accept the OAuth authorization

The client then securely provides an access token for subsequent requests.

HTTP Basic Authentication

The MCP Server in HTTP Basic authentication mode requires an API Key for authentication.

You need to provide a Base64-encoded string of your API Key and API Secret in the format API_KEY:API_SECRET.

If creating a new API Key for MCP Server access, you can copy the Base64-encoded string from the Honeydew Studio UI at the time of creation.

You can use the following command to generate the Base64-encoded string:

```bash theme={null} echo -n ':' | base64 ``` Use PowerShell:

```powershell theme={null}
[Convert]::ToBase64String(
  [Text.Encoding]::UTF8.GetBytes(
    "<API_KEY>:<API_SECRET>"
  )
)
```

Provide the encoded string in the Authorization header as follows:

Authorization: Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>

Configuration

The workspace and branch are set at the session level using the list_workspaces, list_workspace_branches and set_session_workspace_and_branch tools. You can also create new branches with create_workspace_branch. Call these tools from your AI assistant after connecting to the MCP server.

You can optionally provide these headers in your MCP server configuration:

Workspace: Pin the workspace for all requests (optional)
Branch: Pin a specific workspace branch for all requests (optional, defaults to prod if workspace is set)
Honeydew-Client: Identify the MCP client (optional, auto-detected from the connected tool). Pass this header to provide a specific client identifier.
ReadonlyToolsOnly: Set to true to expose only read-only tools (optional)

The MCP server uses the `Mcp-Session-Id` response header to maintain session state, including the active workspace and branch. See the [MCP session management specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#session-management) for details.

Supported Clients

Claude Code CLI

#### Plugin Installation

Honeydew provides a plugins repository with skills and tools for building semantic models and analyzing data through natural conversation. Installing the plugin sets up the Honeydew MCP servers automatically.

Launch Claude Code with claude, then add the marketplace:

/plugin marketplace add honeydew-ai/honeydew-ai-coding-agents-plugins

Then install the Honeydew plugin from the marketplace:

/plugin install honeydew-ai@honeydew-ai-claude-plugins

Then reload plugins to activate:

/reload-plugins

Updating plugins

To update the Honeydew marketplace plugins, launch Claude Code with claude, then:

Write /plugin and select Marketplaces in the selector at the top
Select honeydew-ai-coding-agents-plugins
Click Update marketplace

To receive updates automatically, select Enable auto-update in the marketplace settings.

MCP Setup

Use this section if your organization uses a custom Honeydew endpoint, or if you prefer to configure the MCP servers without installing the plugin. Disable the Honeydew MCP connection added by the plugin, then add your custom endpoint using the instructions below.

Honeydew provides two MCP servers:

Honeydew MCP — connects Claude Code to the Honeydew Semantic Layer for model exploration, data querying, and model management
Honeydew Documentation MCP — gives Claude Code access to Honeydew documentation. No authentication required. Add it with:
```
claude mcp add --transport http honeydew-docs \
    https://honeydew.ai/docs/mcp
```

Use one of the following methods to add the Honeydew MCP server:

      Launch Claude Code with `claude`.
      You'll be prompted to authenticate with OAuth to Honeydew.
    </Tab>

    <Tab title="API Key">
      ```bash theme={null}
      claude mcp add --transport http honeydew \
          https://mcp.honeydew.cloud/mcp \
          --header "Authorization: Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
      ```
    </Tab>
  </Tabs>
</Tab>

<Tab title="JSON configuration">
  Save the following to `honeydew-mcp.json`:

  <Tabs>
    <Tab title="OAuth (recommended)">
      ```json theme={null}
      {
        "type": "http",
        "url": "https://mcp.honeydew.cloud/mcp"
      }
      ```

      Then register it with:

      ```bash theme={null}
      claude mcp add honeydew ./honeydew-mcp.json
      ```

      Launch Claude Code with `claude`.
      You'll be prompted to authenticate with OAuth to Honeydew.
    </Tab>

    <Tab title="API Key">
      ```json theme={null}
      {
        "type": "http",
        "url": "https://mcp.honeydew.cloud/mcp",
        "headers": {
          "Authorization": "Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
        }
      }
      ```

      Then register it with:

      ```bash theme={null}
      claude mcp add honeydew ./honeydew-mcp.json
      ```
    </Tab>
  </Tabs>
</Tab>

<Tab title=".mcp.json">
  Add the following to your `.mcp.json` file:

  <Tabs>
    <Tab title="OAuth (recommended)">
      ```json theme={null}
      {
        "mcpServers": {
          "honeydew": {
            "type": "http",
            "url": "https://mcp.honeydew.cloud/mcp"
          }
        }
      }
      ```

      Launch Claude Code with `claude`.
      You'll be prompted to authenticate with OAuth to Honeydew.
    </Tab>

    <Tab title="API Key">
      ```json theme={null}
      {
        "mcpServers": {
          "honeydew": {
            "type": "http",
            "url": "https://mcp.honeydew.cloud/mcp",
            "headers": {
              "Authorization": "Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
            }
          }
        }
      }
      ```
    </Tab>
  </Tabs>
</Tab>

**Using environment variables for API Key authentication**

To avoid storing sensitive values directly in configuration files,
Claude Code supports
[environment variable expansion](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json)
using the `${VAR_NAME}` syntax.

Set the `HONEYDEW_API_KEY` environment variable,
then reference it in your configuration:

```bash theme={null}
claude mcp add --transport http honeydew \
    https://mcp.honeydew.cloud/mcp \
    --header "Authorization: Basic ${HONEYDEW_API_KEY}"
```

Claude Code resolves `${VAR_NAME}` references
at runtime from your environment.

Removing the MCP server

To remove the Honeydew MCP server:

claude mcp remove honeydew

To remove the Honeydew Documentation MCP server:

claude mcp remove honeydew-docs

Claude Desktop

#### Plugin Installation

Go to Settings -> Customize
Click Browse Plugins
Go to the Personal tab
Click the + icon and choose Add marketplace from GitHub
Enter honeydew-ai/honeydew-ai-coding-agents-plugins in the input box
The Honeydew AI plugin appears. Install it.

MCP Setup

Honeydew provides two MCP servers:

Honeydew MCP — connects Claude Desktop to the Honeydew Semantic Layer for model exploration, data querying, and model management
Honeydew Documentation MCP — gives Claude Desktop access to Honeydew documentation. No authentication required.

Claude Code mode

When using Claude Desktop in Claude Code mode, follow the Claude Code CLI instructions instead.

If your organization uses a custom Honeydew hostname, replace `https://mcp.honeydew.cloud/mcp` with your tenant hostname. You can find the hostname in **Settings > MCP Server** in Honeydew Studio.

To add the Honeydew MCP in Cowork mode:

Go to Settings -> Connectors -> Add custom connector
Enter honeydew in the Name field
Enter https://mcp.honeydew.cloud/mcp in the Remote MCP server URL field
Click Add

You'll be prompted to authenticate with OAuth to Honeydew when first connecting.

To add the Honeydew Documentation MCP:

Go to Settings -> Connectors -> Add custom connector
Enter honeydew-docs in the Name field
Enter https://honeydew.ai/docs/mcp in the Remote MCP server URL field
Click Add

Removing the MCP server

To remove the Honeydew MCP server in Cowork mode:

Go to Settings -> Connectors
Find the honeydew connector and click the delete icon

To remove the Honeydew Documentation MCP server:

Go to Settings -> Connectors
Find the honeydew-docs connector and click the delete icon

Claude.ai

#### Plugin Installation

Honeydew provides a plugins repository with skills and tools for building semantic models and analyzing data through natural conversation. Installing the plugin sets up both the Honeydew MCP server and the Honeydew Documentation MCP server automatically.

Download the plugin zip: honeydew-ai-claude.zip
In Claude.ai, go to Settings -> Plugins -> Add plugin -> Upload zip
Upload the zip — the plugin appears in your private marketplace

MCP Setup

Use this section if your organization uses a custom Honeydew endpoint, or if you prefer to configure the MCP servers without installing the plugin. Remove the Honeydew MCP connector added by the plugin, then add your custom endpoint using the instructions below.

Honeydew provides two MCP servers:

Honeydew MCP — connects Claude.ai to the Honeydew Semantic Layer for model exploration, data querying, and model management
Honeydew Documentation MCP — gives Claude.ai access to Honeydew documentation. No authentication required.

If your organization uses a custom Honeydew hostname, replace `https://mcp.honeydew.cloud/mcp` with your tenant hostname. You can find the hostname in **Settings > MCP Server** in Honeydew Studio.

To add the Honeydew MCP server:

Go to Settings -> Connectors -> Add custom connector
Enter honeydew in the Name field
Enter https://mcp.honeydew.cloud/mcp in the Remote MCP server URL field
Click Add

You'll be prompted to authenticate with OAuth to Honeydew when first connecting.

To add the Honeydew Documentation MCP:

Go to Settings -> Connectors -> Add custom connector
Enter honeydew-docs in the Name field
Enter https://honeydew.ai/docs/mcp in the Remote MCP server URL field
Click Add

Removing the MCP server

To remove the Honeydew MCP server:

Go to Settings -> Connectors
Find the honeydew connector and click the delete icon

To remove the Honeydew Documentation MCP server:

Go to Settings -> Connectors
Find the honeydew-docs connector and click the delete icon

Cortex Code CLI

#### Plugin Installation

Launch Cortex Code CLI with cortex, then install the plugin:

/plugin install honeydew-ai/honeydew-ai-coding-agents-plugins

MCP Setup

Honeydew provides two MCP servers:

Honeydew MCP — connects Cortex Code CLI to the Honeydew Semantic Layer for model exploration, data querying, and model management
Honeydew Documentation MCP — gives Cortex Code CLI access to Honeydew documentation. No authentication required. Add it with:
```
cortex mcp add honeydew-docs \
    https://honeydew.ai/docs/mcp \
    --type http
```

      Launch Cortex Code CLI with `cortex`.
      You'll be prompted to authenticate
      with OAuth to Honeydew.
    </Tab>

    <Tab title="API Key">
      ```bash theme={null}
      cortex mcp add honeydew \
          https://mcp.honeydew.cloud/mcp \
          --type http \
          -H "Authorization: Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
      ```
    </Tab>
  </Tabs>
</Tab>

<Tab title="JSON configuration">
  Save the following to `honeydew-mcp.json`:

  <Tabs>
    <Tab title="OAuth (recommended)">
      ```json theme={null}
      {
        "type": "http",
        "url": "https://mcp.honeydew.cloud/mcp"
      }
      ```

      Then register it with:

      ```bash theme={null}
      cortex mcp add honeydew ./honeydew-mcp.json --type http
      ```

      Launch Cortex Code CLI with `cortex`.
      You'll be prompted to authenticate
      with OAuth to Honeydew.
    </Tab>

    <Tab title="API Key">
      ```json theme={null}
      {
        "type": "http",
        "url": "https://mcp.honeydew.cloud/mcp",
        "headers": {
          "Authorization": "Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
        }
      }
      ```

      Then register it with:

      ```bash theme={null}
      cortex mcp add honeydew ./honeydew-mcp.json --type http
      ```
    </Tab>
  </Tabs>
</Tab>

<Tab title="mcp.json">
  Add the following to
  `~/.snowflake/cortex/mcp.json`:

  <Tabs>
    <Tab title="OAuth (recommended)">
      ```json theme={null}
      {
        "mcpServers": {
          "honeydew": {
            "type": "http",
            "url": "https://mcp.honeydew.cloud/mcp"
          }
        }
      }
      ```

      Launch Cortex Code CLI with `cortex`.
      You'll be prompted to authenticate
      with OAuth to Honeydew.
    </Tab>

    <Tab title="API Key">
      ```json theme={null}
      {
        "mcpServers": {
          "honeydew": {
            "type": "http",
            "url": "https://mcp.honeydew.cloud/mcp",
            "headers": {
              "Authorization": "Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
            }
          }
        }
      }
      ```
    </Tab>
  </Tabs>
</Tab>

Removing the MCP server

To remove the Honeydew MCP server:

cortex mcp remove honeydew

To remove the Honeydew Documentation MCP server:

cortex mcp remove honeydew-docs

Cursor

#### Plugin Installation

In your team or organization settings, go to cursor.com/dashboard/plugins (or click Plugins on the left side menu)
Scroll down to Team Marketplaces and either click an existing Marketplace, or click Add Marketplace to create a new one. If creating a new one, enter a name and create it.
Within the Marketplace, click Add Plugin, paste the Honeydew plugin GitHub repository path: https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins and click Add 1 plugin
Optionally, enable auto-refresh in the Marketplace page so the plugin updates automatically when new versions are released.
Go back to the plugins page (cursor.com/dashboard/plugins), search for the Honeydew plugin, and click Add

MCP Setup

Honeydew provides two MCP servers:

Honeydew MCP — connects Cursor to the Honeydew Semantic Layer for model exploration, data querying, and model management
Honeydew Documentation MCP — gives Cursor access to Honeydew documentation. No authentication required.

If your organization uses a custom Honeydew hostname, replace `https://mcp.honeydew.cloud/mcp` with your tenant hostname. You can find the hostname in **Settings > MCP Server** in Honeydew Studio.

To add the Honeydew MCP:

Open the Cursor application
Go to Settings -> Cursor Settings -> Tools & MCP
Click New MCP Server

Add the following configuration:

```json theme={null} { "name": "honeydew", "type": "http", "url": "https://mcp.honeydew.cloud/mcp" } ```

<Tab title="API Key">
  ```json theme={null}
  {
    "name": "honeydew",
    "type": "http",
    "url": "https://mcp.honeydew.cloud/mcp",
    "headers": {
      "Authorization": "Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
    }
  }
  ```
</Tab>

Click Save

To add the Honeydew Documentation MCP:

Go to Settings -> Cursor Settings -> Tools & MCP
Click New MCP Server

Add the following configuration:

{
  "name": "honeydew-docs",
  "type": "http",
  "url": "https://honeydew.ai/docs/mcp"
}

Click Save

Removing the MCP server

To remove the Honeydew MCP server:

Go to Settings -> Cursor Settings -> Tools & MCP
Find honeydew in the list and click the delete icon

To remove the Honeydew Documentation MCP server:

Go to Settings -> Cursor Settings -> Tools & MCP
Find honeydew-docs in the list and click the delete icon

Databricks Genie Code

MCP servers are only supported in Genie Code Agent mode. For more details, see the [Databricks MCP documentation](https://docs.databricks.com/aws/en/generative-ai/mcp/).

Prerequisites:

Genie Code enabled in your Databricks workspace
CREATE CONNECTION privilege on the Unity Catalog metastore

1. Navigate to **Catalog** → **Connections** → **Create a connection** 2. On the **Connection basics** screen: * Set **Connection name** to `honeydew-mcp` * Set **Connection type** to **HTTP** * Set **Auth type** to **Dynamic Client Registration** * Click **Next** 3. On the **Authentication** screen: * Set **Host** to `https://mcp.honeydew.cloud` * Leave **Port** as `443` * Set **OAuth scope** to `openid` * Click **Next** 4. On the **Connection details** screen: * Check **Is MCP connection** * Set **Base path** to `/mcp` * Click **Create connection**

    <Tab title="SQL">
      Run the following SQL in a Databricks notebook or SQL editor:

      ```sql theme={null}
      CREATE OR REPLACE CONNECTION `honeydew-mcp` TYPE HTTP
      OPTIONS (
        host 'https://mcp.honeydew.cloud',
        base_path '/mcp',
        is_mcp_connection 'true',
        oauth_scope 'openid'
      );

      DESCRIBE CONNECTION `honeydew-mcp`;
      ```
    </Tab>
  </Tabs>

  <Note>
    If your organization uses a custom Honeydew hostname, replace
    `https://mcp.honeydew.cloud` with your tenant hostname.
    You can find your hostname in **Settings > MCP Server** in Honeydew Studio.
  </Note>
</Step>

<Step title="Log in to the connection">
  Navigate to **Catalog** → **Connections** → `honeydew-mcp`
  and click **Login** in the upper right corner
  to authenticate and verify the connection.
</Step>

<Step title="Grant connection access">
  Grant the `USE CONNECTION` privilege to any users or roles
  that need access to the Honeydew MCP server:

  ```sql theme={null}
  GRANT USE CONNECTION ON CONNECTION `honeydew-mcp` TO <user-or-role>;
  ```
</Step>

<Step title="Add the MCP server in Genie Code">
  1. Open Genie Code and click the gear icon
  2. Navigate to **MCP Servers** → **Add Server**
  3. Select **External MCP server**
  4. Choose the `honeydew-mcp` connection you created
  5. Log in to the connection when prompted
  6. Click **Save**

  <Note>
    Databricks limits MCP to 20 tools across all configured servers.
    If you need to adjust which Honeydew tools are available,
    use the Genie Code MCP settings to enable or disable specific tools.
  </Note>
</Step>

Removing the MCP server

To remove the Honeydew MCP server from Genie Code:

Open Genie Code and click the gear icon
Navigate to MCP Servers
Find honeydew-mcp and click Remove

To also remove the underlying Unity Catalog connection, run the following SQL:

DROP CONNECTION `honeydew-mcp`;

GitHub Copilot CLI

#### MCP Server If your organization uses a custom Honeydew hostname, replace `https://mcp.honeydew.cloud/mcp` with your tenant hostname. You can find the hostname in **Settings > MCP Server** in Honeydew Studio.

Launch GitHub Copilot CLI with copilot
Type /mcp add to open the server configuration form
Fill in the following fields:
- Name: honeydew
- Type: http
- URL: https://mcp.honeydew.cloud/mcp
- HTTP Headers:
  No additional headers are needed for OAuth. ```json theme={null} { "Authorization": "Basic " } ```
Press Ctrl+S to save

Use /mcp show to verify the server is connected.

AI Coding Agent Plugins

Honeydew provides a plugins repository with skills and tools for building semantic models and analyzing data through natural conversation.

Add the marketplace to Copilot CLI:

/plugin marketplace add honeydew-ai/honeydew-ai-coding-agents-plugins

Then install the Honeydew plugin from the marketplace:

/plugin install honeydew-ai@honeydew-ai-github-copilot-plugins

Honeydew Documentation MCP

Give Copilot CLI access to the Honeydew documentation through a separate MCP server. No authentication is required.

Launch GitHub Copilot CLI with copilot
Type /mcp add to open the server configuration form
Fill in the following fields:
- Name: honeydew-docs
- Type: http
- URL: https://honeydew.ai/docs/mcp
Press Ctrl+S to save

Removing the MCP server

To remove the Honeydew MCP server, launch GitHub Copilot CLI with copilot, then type:

/mcp remove honeydew

To remove the Honeydew Documentation MCP server:

/mcp remove honeydew-docs

Gemini CLI

Run the following command to add the Honeydew MCP server:

```bash theme={null} gemini mcp add --transport http honeydew \ https://mcp.honeydew.cloud/mcp ```

  Launch Gemini CLI with `gemini`.
  You'll be prompted to authenticate with OAuth to Honeydew.
</Tab>

<Tab title="API Key">
  ```bash theme={null}
  gemini mcp add --transport http honeydew \
      https://mcp.honeydew.cloud/mcp \
      --header "Authorization: Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
  ```
</Tab>

AI Coding Agent Skills

Honeydew provides a skills repository with skills for building semantic models and analyzing data through natural conversation.

Run the following command to install the Honeydew skills:

gemini skills install \
    https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins.git \
    --path .gemini/skills

Honeydew Documentation MCP

Give Gemini CLI access to the Honeydew documentation through a separate MCP server. No authentication is required.

gemini mcp add --transport http honeydew-docs \
    https://honeydew.ai/docs/mcp

Removing the MCP server

To remove the Honeydew MCP server:

gemini mcp remove honeydew

To remove the Honeydew Documentation MCP server:

gemini mcp remove honeydew-docs

VS Code and GitHub Copilot

#### Plugin Installation

Add the Honeydew marketplace

Open your VS Code settings.json (open the Command Palette with CMD+Shift+P on macOS or Ctrl+Shift+P on Windows/Linux, then select Preferences: Open User Settings (JSON))

Add the Honeydew marketplace to the chat.plugins.marketplaces setting:

"chat.plugins.marketplaces": [
  "honeydew-ai/honeydew-ai-coding-agents-plugins"
]

Install the plugin

Open the Extensions view (CMD+Shift+X on macOS or Ctrl+Shift+X on Windows/Linux)
Enter @agentPlugins in the search field
Find the Honeydew AI plugin and click Install

The first time you install a plugin from a new marketplace, VS Code shows a trust prompt — review the marketplace source before confirming.

Update the plugin

If extensions.autoUpdate is enabled in VS Code settings, the plugin updates automatically. To update manually, open the Command Palette and run Extensions: Check for Extension Updates.

MCP Server

Honeydew provides two MCP servers:

Honeydew MCP — connects VS Code to the Honeydew Semantic Layer for model exploration, data querying, and model management
Honeydew Documentation MCP — gives VS Code access to Honeydew documentation. No authentication required.

If your organization uses a custom Honeydew hostname, replace `https://mcp.honeydew.cloud/mcp` with your tenant hostname. You can find the hostname in **Settings > MCP Server** in Honeydew Studio.

Open the Command Palette with CMD+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
Select MCP: Add Server...
Choose HTTP (HTTP or Server-Sent Events)
Enter the Honeydew MCP server URL: https://mcp.honeydew.cloud/mcp
Enter honeydew as the server name

This adds the server to your .vscode/mcp.json file. Open the file and add headers as needed:

```json theme={null} { "servers": { "honeydew": { "type": "http", "url": "https://mcp.honeydew.cloud/mcp" } } } ```

<Tab title="API Key">
  ```json theme={null}
  {
    "servers": {
      "honeydew": {
        "type": "http",
        "url": "https://mcp.honeydew.cloud/mcp",
        "headers": {
          "Authorization": "Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
        }
      }
    }
  }
  ```
</Tab>

Honeydew Documentation MCP

Give VS Code access to the Honeydew documentation through a separate MCP server. No authentication is required.

Add the following to your .vscode/mcp.json:

{
  "servers": {
    "honeydew-docs": {
      "type": "http",
      "url": "https://honeydew.ai/docs/mcp"
    }
  }
}

Removing the MCP server

To remove the Honeydew MCP server, open .vscode/mcp.json and delete the honeydew entry from the servers object. To remove the Honeydew Documentation MCP server, delete the honeydew-docs entry from the same file.

Codex CLI

#### Plugin Installation

Add the marketplace to Codex:

codex plugin marketplace add honeydew-ai/honeydew-ai-coding-agents-plugins

Then launch Codex with codex and type /plugins to browse and install the Honeydew AI plugin.

Updating plugins

To update the Honeydew marketplace, run:

codex plugin marketplace upgrade honeydew-ai-coding-agents-plugins

Then launch Codex and type /plugins to apply updates.

MCP Setup

Honeydew provides two MCP servers:

Honeydew MCP — connects Codex to the Honeydew Semantic Layer for model exploration, data querying, and model management
Honeydew Documentation MCP — gives Codex access to Honeydew documentation. No authentication required. Add it with:
```
codex mcp add honeydew-docs \
    --url https://honeydew.ai/docs/mcp
```

If your organization uses a custom Honeydew hostname, replace `https://mcp.honeydew.cloud/mcp` with your tenant hostname. You can find the hostname in **Settings > MCP Server** in Honeydew Studio.

Command line

codex mcp add honeydew \
    --url https://mcp.honeydew.cloud/mcp

Then launch Codex with codex. You'll be prompted to authenticate with OAuth to Honeydew.

After adding the server, open the configuration file at ~/.codex/config.toml and add headers to the [mcp_servers.honeydew] section as needed.

TOML configuration

Add the following to ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.honeydew]
url = "https://mcp.honeydew.cloud/mcp"

[mcp_servers.honeydew.env_http_headers]
Authorization = "HONEYDEW_AUTH"

Set the HONEYDEW_AUTH environment variable to Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET> (see Authentication).

Removing the MCP server

To remove the Honeydew MCP server:

codex mcp remove honeydew

To remove the Honeydew Documentation MCP server:

codex mcp remove honeydew-docs

Codex

Open the Codex application
Go to Settings -> MCP Servers
Under Custom servers, click Add Server
Set the server name to honeydew
Choose Streamable HTTP as the transport type
Set the URL to https://mcp.honeydew.cloud/mcp
Leave the Bearer token environment variable field empty
Configure authentication as follows:

OAuth authentication

Codex redirects you to authenticate with Honeydew when connecting. No additional configuration is needed.

HTTP Basic authentication

Add an Authorization header to the headers list above with the value Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET> (see Authentication).

Troubleshooting MCP authentication

If the Honeydew MCP server is not authenticated in Codex and the "Authenticate" option does not appear:

Install the Codex CLI
Run codex mcp login honeydew

AI Coding Agent Skills

Honeydew provides a skills repository with skills for building semantic models and analyzing data through natural conversation.

Launch Codex, then run:

$skill-installer Sync my local skills with
https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins.git:
1) Enumerate repo skills
2) For skills that already exist locally, back them up and replace them with the repo version
3) Install any missing skills
4) Show updated/installed/skipped summary
5) Ask before any destructive overwrite

Honeydew Documentation MCP

Give Codex access to the Honeydew documentation through a separate MCP server. No authentication is required.

Go to Settings -> MCP Servers
Under Custom servers, click Add Server
Set the server name to honeydew-docs
Choose Streamable HTTP as the transport type
Set the URL to https://honeydew.ai/docs/mcp

Removing the MCP server

To remove the Honeydew MCP server:

Go to Settings -> MCP Servers
Find honeydew under Custom servers and click Remove

To remove the Honeydew Documentation MCP server:

Go to Settings -> MCP Servers
Find honeydew-docs under Custom servers and click Remove

Antigravity

Open the Antigravity editor
Click the ... dropdown at the top of the agent panel
Click Manage MCP Servers
Click View raw config

Add the following to mcp_config.json:

```json theme={null} { "name": "honeydew", "type": "http", "url": "https://mcp.honeydew.cloud/mcp" } ```

<Tab title="API Key">
  ```json theme={null}
  {
    "name": "honeydew",
    "type": "http",
    "url": "https://mcp.honeydew.cloud/mcp",
    "headers": {
      "Authorization": "Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
    }
  }
  ```
</Tab>

Save the file

Honeydew Documentation MCP

Give Antigravity access to the Honeydew documentation through a separate MCP server. No authentication is required.

Open the Antigravity editor
Click the ... dropdown at the top of the agent panel
Click Manage MCP Servers
Click View raw config

Add the following to mcp_config.json:

{
  "name": "honeydew-docs",
  "type": "http",
  "url": "https://honeydew.ai/docs/mcp"
}

Save the file

Removing the MCP server

To remove the Honeydew MCP server:

Open the Antigravity editor
Click the ... dropdown at the top of the agent panel
Click Manage MCP Servers
Click View raw config
Remove the honeydew and honeydew-docs entries from mcp_config.json
Save the file

OpenCode

  ```bash theme={null}
  opencode mcp add
  ```

  When prompted, enter the following values:

  1. **Location**: Choose your preferred scope (current project or global)
  2. **MCP server name**: `honeydew`
  3. **MCP server type**: `Remote`
  4. **MCP server URL**: `https://mcp.honeydew.cloud/mcp`
  5. **OAuth authentication**: `Yes`
  6. **Preregistered client ID**: `No`
</Tab>

<Tab title="JSON configuration">
  Add the following to your `opencode.jsonc` file:

  <Tabs>
    <Tab title="OAuth (recommended)">
      ```json theme={null}
      {
        "$schema": "https://opencode.ai/config.json",
        "mcp": {
          "honeydew": {
            "type": "remote",
            "url": "https://mcp.honeydew.cloud/mcp",
            "oauth": {}
          }
        }
      }
      ```

      Then authenticate with Honeydew:

      ```bash theme={null}
      opencode mcp auth honeydew
      ```

      This opens a browser window to complete the OAuth authentication flow.
    </Tab>

    <Tab title="API Key">
      ```json theme={null}
      {
        "$schema": "https://opencode.ai/config.json",
        "mcp": {
          "honeydew": {
            "type": "remote",
            "url": "https://mcp.honeydew.cloud/mcp",
            "headers": {
              "Authorization": "Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
            }
          }
        }
      }
      ```
    </Tab>
  </Tabs>
</Tab>

Re-authentication

To re-authenticate, check your status and log out first:

opencode mcp auth list
opencode mcp logout honeydew
opencode mcp auth honeydew

Honeydew Documentation MCP

Give OpenCode access to the Honeydew documentation through a separate MCP server. No authentication is required.

Run `opencode mcp add` and enter the following values:

  1. **MCP server name**: `honeydew-docs`
  2. **MCP server type**: `Remote`
  3. **MCP server URL**: `https://honeydew.ai/docs/mcp`
  4. **OAuth authentication**: `No`
</Tab>

<Tab title="JSON configuration">
  Add the following to your `opencode.jsonc` file:

  ```json theme={null}
  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "honeydew-docs": {
        "type": "remote",
        "url": "https://honeydew.ai/docs/mcp"
      }
    }
  }
  ```
</Tab>

Removing the MCP server

To remove the Honeydew MCP server, remove the honeydew entry from your opencode.jsonc file. To remove the Honeydew Documentation MCP server, remove the honeydew-docs entry from the same file.

Kiro

The Kiro IDE and the Kiro CLI share the same MCP configuration files, so the steps below apply to both.

MCP Server

Kiro reads MCP servers from two configuration files:

Workspace: .kiro/settings/mcp.json (specific to the current project)
User: ~/.kiro/settings/mcp.json (applies across all workspaces)

If both files exist, the workspace configuration takes precedence.

If your organization uses a custom Honeydew hostname, replace `https://mcp.honeydew.cloud/mcp` with your tenant hostname. You can find the hostname in **Settings > MCP Server** in Honeydew Studio.

Add the Honeydew MCP server to one of these mcp.json files (workspace or user):

```json theme={null} { "mcpServers": { "honeydew": { "url": "https://mcp.honeydew.cloud/mcp" } } } ```

  When first connecting to Honeydew, Kiro provides an authentication URL.
  Open it in your browser to complete the OAuth authentication flow.
</Tab>

<Tab title="API Key">
  ```json theme={null}
  {
    "mcpServers": {
      "honeydew": {
        "url": "https://mcp.honeydew.cloud/mcp",
        "headers": {
          "Authorization": "Basic <YOUR_BASE64_ENCODED_API_KEY_AND_SECRET>"
        }
      }
    }
  }
  ```
</Tab>

In the Kiro CLI, run /mcp to verify the server is connected. In the Kiro IDE, the server appears under the MCP panel.

Honeydew Documentation MCP

Give Kiro access to the Honeydew documentation through a separate MCP server. No authentication is required.

Add the following to your mcp.json:

{
  "mcpServers": {
    "honeydew-docs": {
      "url": "https://honeydew.ai/docs/mcp"
    }
  }
}

Removing the MCP server

To remove the Honeydew MCP server, delete the honeydew entry from your mcp.json. To remove the Honeydew Documentation MCP server, delete the honeydew-docs entry from the same file.

Other Clients

Any MCP-compatible client can connect to the Honeydew MCP Server using the standard HTTP transport.

Use the following JSON configuration as a starting point:

If your organization uses a custom Honeydew hostname, replace `https://mcp.honeydew.cloud/mcp` with your tenant hostname. You can find the hostname in **Settings > MCP Server** in Honeydew Studio. ```json theme={null} { "name": "honeydew", "type": "http", "url": "https://mcp.honeydew.cloud/mcp" } ``` ```json theme={null} { "name": "honeydew", "type": "http", "url": "https://mcp.honeydew.cloud/mcp", "headers": { "Authorization": "Basic " } } ```

See Server URL, Authentication, and Configuration for details on each parameter.

Example Usage

Once connected, you can prompt your AI assistant with questions like:

"What entities are available in the semantic model?"
"Show me the attributes and metrics for the orders entity"
"What domains are defined in the model?"
"What tables are in the analytics schema?"
"How many orders were placed last month?"
"Create a new metric for total revenue on the orders entity"
"What is the average order value by region for the last quarter?"

Troubleshooting

OAuth Authentication Problems

Verify your client supports OAuth, ensure you have the necessary Honeydew workspace permissions, and attempt re-authentication through your client's MCP management interface.

Re-authenticating in Claude Code

Type /mcp, select the Honeydew MCP from the list, choose "Clear authentication" or "Authenticate", then follow the browser OAuth prompts to reconnect to Honeydew.

Connection Issues

Confirm the MCP server URL matches https://mcp.honeydew.cloud/mcp and verify your client's MCP configuration syntax is correct. If your organization uses a custom hostname, check that the URL matches your tenant hostname that appears in Settings > MCP Server in Honeydew Studio.

Missing Tools

Verify authentication succeeded, check your Honeydew workspace access permissions, and review your client's console for error messages.

For additional support, contact Honeydew support at [email protected].

Tools Available

Tools marked as read-only do not modify the semantic model or the data warehouse.

To expose only read-only tools, set the `ReadonlyToolsOnly: true` header in your MCP server configuration. When enabled, the server returns only tools that do not modify the semantic model or the data warehouse.

Session & Workspace

`list_workspaces`

read-only

List all available workspaces. Returns the workspace name, and the data warehouse type (snowflake, databricks, or bigquery). Use the data warehouse type to inform semantic model implementation.

`list_workspace_branches`

read-only

List all branches available for a workspace.

The name of the workspace.

`get_session_workspace_and_branch`

read-only

Get the workspace and branch set for the current session.

`set_session_workspace_and_branch`

read-only

Set the workspace and branch to use for the current session. All subsequent tool calls in the session use this workspace and branch.

The name of the workspace. The branch to use.

`create_workspace_branch`

Create a new branch for an existing workspace. The branch is created from the current state of the workspace's prod branch. If no workspace is pinned via headers, the session switches to the new branch automatically.

Name of the workspace to create a branch for. Name of the new branch to create.

`delete_workspace_branch`

Delete a branch from a workspace. This is a destructive, irreversible operation. Always confirm the workspace name and branch name with the user before calling this tool. The prod branch cannot be deleted. If the deleted branch is the current session branch, the session switches to prod automatically.

Name of the workspace containing the branch to delete. Name of the branch to delete.

`get_branch_history`

read-only

Get the change history for the current session's branch. Returns a list of changes showing what semantic objects were modified, by whom, and when.

Maximum number of changes to return.

`create_pr_for_working_branch`

Create a pull request for the current session's working branch. Returns the PR URL on success.

Title for the pull request. Description for the pull request.

Question & Analysis

`initiate_analysis`

read-only

Start or continue a data analysis. Returns a conversation_id — use monitor_analysis to poll for progress and results, and abort_analysis to stop it early. See Deep Analysis for more details.

The natural language question to ask. Agent name for a new conversation. Omit for follow-up questions — the agent is inherited from the existing conversation. Existing conversation ID to continue, or omit to start a new conversation.

`monitor_analysis`

read-only

Poll for new progress messages from an in-progress analysis. Each call returns only messages since the last call. Poll repeatedly until status is DONE or NO_CHAT_CURRENTLY_RUNNING.

Conversation ID returned by `initiate_analysis`. Maximum number of messages to return per call. Message ID to replay from. Use `last_received_message_id` from a previous result to recover missed messages.

`get_analysis_step_details`

read-only

Retrieve full details for a specific analysis step, including the semantic query, SQL statement, context used, and data retrieved in that step.

Conversation ID returned by `initiate_analysis`. Step ID from `monitor_analysis` (e.g. `STEP/0`).

`abort_analysis`

read-only

Abort an in-progress analysis. Can be resumed from the aborted point with initiate_analysis.

Conversation ID returned by `initiate_analysis`.

`list_analysis_chats`

read-only

Return a paginated list of analysis conversations for the current workspace, sorted by creation time (newest first). Admins see all conversations; non-admins see only their own. Each entry includes the conversation ID, title, user feedback, domain, agent, creation time, and the display name of the user who created it.

Maximum number of conversations to return. Number of conversations to skip for pagination.

`provide_analysis_feedback`

Set or clear feedback on a specific analysis conversation. There is a single feedback entry per conversation (not per question) — it should reflect the overall quality of the entire conversation flow.

Call this after monitor_analysis completes and the user expresses satisfaction or dissatisfaction with the result. Use a short affirmative string for positive feedback (e.g. Good), or the format <Reason>: <details> for negative feedback, where Reason is one of Chart Issue, Data Issue, Wrong Judgement, or Other.

Conversation ID of the analysis conversation. Feedback text to store, or `null` to clear existing feedback.

`get_stored_conversation`

read-only

Return all messages from an existing analysis conversation. Use this to review the full content of a previous conversation. is_complete in the response indicates whether the conversation reached a terminal state.

Conversation ID from `list_analysis_chats`. If `true`, include `step_start` and `step_insight` progress entries. If `false`, return only final responses and plan/interpretation messages.

Browse & Discovery

`list_entities`

read-only

List all entities in the semantic model with their names, descriptions, and keys.

`get_entity`

read-only

Get detailed information about an entity, including its attributes, metrics, datasets, relations, and YAML definition.

The name of the entity.

`get_field`

read-only

Get detailed information about a specific field (attribute or metric) within an entity, including its YAML definition.

The name of the entity containing the field. The name of the field.

`list_domains`

read-only

List all domains in the semantic model with their names, descriptions, and entities.

`get_domain`

read-only

Get detailed information about a domain, including its entities, filters, parameters, and YAML definition.

The name of the domain.

`search_model`

read-only

Search the semantic model for entities, attributes, metrics, datasets, dynamic datasets, domains, and global parameters matching a query string.

Use entity.field syntax to scope the search to fields within a specific entity. For example, customers.balance finds the balance field on entities matching customers; customers. returns all fields of matching entities. In OR/AND mode, partial matches apply to both the entity and field parts — cust.bal matches customers.balance.

The search query string. Controls how the query is matched:

OR — splits by whitespace, returns objects matching any word.
AND — splits by whitespace, returns only objects matching all words.
EXACT — uses the full string as-is, returns objects whose name or display name is an exact match.

Warehouse Discovery

`list_databases`

read-only

List all databases available in the connected data warehouse.

`list_schemas`

read-only

List all schemas in a specific database in the connected data warehouse.

The database name.

`list_tables`

read-only

List tables/views in a specific database and schema in the connected data warehouse.

The database name. The schema name.

`get_table_info`

read-only

Get detailed information about a warehouse table/view, including its columns and metadata.

The database name. The schema name. The table name.

Semantic Model

`import_tables`

Import tables from the connected data warehouse into the semantic model. Each table becomes an entity with its columns as attributes.

List of fully qualified table names in the format `database.schema.table`.

`create_entity`

Create a new entity in the semantic model from YAML definitions.

The YAML definition for the entity. The YAML definition for the dataset.

`create_object`

Create a new semantic model object from a YAML definition. Supported types: attribute, metric, dynamic dataset, domain, and global parameter.

The YAML definition of the object. Create the object even if validation produces errors.

`update_object`

Update an existing semantic model object from a YAML definition. Supported types: entity, attribute, metric, dataset, dynamic dataset, domain, and global parameter.

The YAML definition of the object. The key of the object to update. Update the object even if validation produces errors.

`validate_object`

read-only

Validate a semantic model object YAML definition without creating or updating it. Supported types: entity, attribute, metric, dataset, dynamic dataset, domain, and global parameter.

The YAML definition to validate. The key of the object to validate against.

`delete_object`

Delete a semantic model object by its key.

The key of the object to delete. Delete the object even if validation produces errors.

Agents

`list_agents`

read-only

List all agents with their names, descriptions, domains, and context references.

`get_agent`

read-only

Get detailed information about an agent, including its YAML frontmatter definition.

Name of the agent to retrieve.

`create_agent`

Create a new agent.

Metadata for the new agent. Hierarchical name (e.g., `growth-analyst`, `finance/budget-analyst`).

<ParamField body="display_name" type="string" required>
  Human-readable name shown in the UI.
</ParamField>

<ParamField body="description" type="string" required>
  Description of the agent's purpose and capabilities.
</ParamField>

<ParamField body="domain" type="string" required>
  The domain this agent operates in.
</ParamField>

<ParamField body="welcome_message" type="string">
  Introductory message shown when a user starts a session.
</ParamField>

<ParamField body="sample_questions" type="string[]">
  Example questions shown to users.
</ParamField>

<ParamField body="context" type="string[]">
  Context item names or glob patterns to load into sessions
  (e.g., `skills/**`, `knowledge/marketing/**`).
</ParamField>

<ParamField body="owner" type="string">
  Owner identifier for the agent.
</ParamField>

Markdown body appended after the frontmatter. This text is injected into the prompt before every analysis session. Create the agent even if validation produces errors.

`update_agent`

Update an existing agent.

Name of the agent to update. Full updated agent definition. All required fields from `create_agent` must be supplied — this is a full replacement, not a partial update. Updated Markdown body for the agent. Update the agent even if validation produces errors.

`delete_agent`

Delete an agent by name.

Name of the agent to delete.

Context Items

`list_context_items`

read-only

List all context items with their types, names, titles, and subtype values.

`get_context_item`

read-only

Get a context item by name.

Name of the context item to retrieve.

`create_context_item`

Create a new context item. Supports instruction and memory types.

Metadata for the new context item. Must be `instruction`.

<ParamField body="name" type="string" required>
  Hierarchical name
  (e.g., `knowledge/customer/churn-analysis`, `skills/reporting`).
</ParamField>

<ParamField body="subtype" type="string" required>
  One of `knowledge`, `skill`, or `instruction`.
</ParamField>

<ParamField body="title" type="string" required>
  Human-readable title for the context item.
</ParamField>

<ParamField body="apply" type="string" required>
  When to apply the context: `always` or `on_demand`.
</ParamField>

<ParamField body="description" type="string">
  Description used by the AI to decide when to load this item
  (required when `apply` is `on_demand`).
</ParamField>

<ParamField body="owner" type="string">
  Owner identifier.
</ParamField>

<ParamField body="labels" type="string[]">
  Labels for organizing context items.
</ParamField>

<ParamField body="related_objects" type="object[]">
  Semantic objects this context item relates to.
  Each object has a `name` (string) and `type` (`domain`, `entity`, or `field`).
</ParamField>

<ParamField body="external_source" type="object">
  External source to fetch content from (for `knowledge` subtype).
  Has `tool` (MCP tool name), `resource_id` (identifier in the external tool),
  and optional `cache_max_age_in_seconds` (default: `3600`).
</ParamField>

Must be `memory`.

<ParamField body="name" type="string" required>
  Hierarchical name (e.g., `events/q4-launch`, `2024/pricing-decision`).
</ParamField>

<ParamField body="subtype" type="string" required>
  One of `event` or `decision_trace`.
</ParamField>

<ParamField body="title" type="string" required>
  Human-readable title for the context item.
</ParamField>

<ParamField body="apply" type="string" required>
  When to apply the context: `always` or `on_demand`.
</ParamField>

<ParamField body="from_date" type="string" required>
  Start date of the memory period in ISO format (e.g., `2024-01-01`).
</ParamField>

<ParamField body="to_date" type="string">
  End date of the memory period in ISO format.
</ParamField>

<ParamField body="description" type="string">
  Description used by the AI to decide when to load this item
  (required when `apply` is `on_demand`).
</ParamField>

<ParamField body="owner" type="string">
  Owner identifier.
</ParamField>

<ParamField body="labels" type="string[]">
  Labels for organizing context items.
</ParamField>

<ParamField body="related_objects" type="object[]">
  Semantic objects this context item relates to.
  Each object has a `name` (string) and `type` (`domain`, `entity`, or `field`).
</ParamField>

<ParamField body="external_source" type="object">
  External source to fetch content from.
  Has `tool` (MCP tool name), `resource_id` (identifier in the external tool),
  and optional `cache_max_age_in_seconds` (default: `3600`).
</ParamField>

Markdown body for the context item's content. Create the context item even if validation produces errors.

`update_context_item`

Update an existing context item.

Name of the context item to update. Full updated context item definition. All required fields from `create_context_item` must be supplied — this is a full replacement, not a partial update. Updated Markdown body for the context item. Update the context item even if validation produces errors.

`delete_context_item`

Delete a context item by name.

Name of the context item to delete.

Query & Preview

`get_sql_from_fields`

read-only

Generate the SQL query for a semantic layer query defined by attributes, metrics, and filters. Returns the SQL without executing it.

Fully qualified attribute names (`entity.attribute_name`). Supports aliases: `entity.attribute_name as alias_name`. Fully qualified metric names (`entity.metric_name`) or SQL expressions (e.g. `SUM(entity.field)`). Supports aliases: `SUM(entity.field) as total`. Filter conditions (e.g. `entity.field = 'value'`, `entity.date_field > '2024-01-01'`). List of fields to order by. Format: `entity.field_name` or `entity.field_name DESC`. Default direction is ASC. When using aliases, order by the alias name. The domain to query against. Maximum number of rows to return. Number of rows to skip for pagination.

`get_data_from_fields`

read-only

Execute a semantic layer query defined by attributes, metrics, and filters, and return the resulting data.