Skip to content

Claude & ChatGPT connector (MCP)

Platform (dbtCharts.com)

This page describes dbt Charts Platform, the hosted product at dbtCharts.com. These features are not part of the open source dct engine.

This is the main way to use dbt Charts from an AI assistant. dbt Charts Platform is a remote MCP server: paste one URL, https://dbtcharts.com/mcp, into Claude or ChatGPT and chat with your boards and your warehouse from there: find a board, read what it shows, run the queries behind it, and have the AI draw new charts inline, all signed in as you, with your own permissions.

It works in the ordinary Claude and ChatGPT apps (web, desktop, and mobile). You don't need a coding agent such as Claude Code or Codex, a git checkout, or the dct CLI: there is nothing to install, and nothing runs on your machine.

By default the connector serves every organization you belong to, including ones you join later, through that one URL. You add it once, not once per organization or project: search spans every project you can reach in those organizations, and each call is still checked against your access to the specific project and data source it touches. You can limit it to specific organizations on the consent screen, and change that later without reconnecting.

This page walks the whole flow: connecting, what the connector can do, what the consent screen grants, and how to see, change, and remove access later.

Looking for dct mcp serve?

The local MCP server that ships with the dct CLI is a different thing, for a few narrower cases such as an editor agent working on files in a local checkout. CLI and MCP for AI assistants compares the options.

Connect from Claude

  1. In Claude, open Settings → Connectors and choose Add custom connector.

  2. Name it (for example, dbt Charts) and paste your server URL: your Platform origin plus /mcp, for example https://dbtcharts.com/mcp.

    Claude's Add custom connector dialog, named dbt Charts, with https://dbtcharts.com/mcp as the server URL

  3. Choose Continue. Claude discovers the sign-in flow on its own, with no client ID or secret to fill in. When you start from Claude Desktop, your browser first opens claude.ai asking Finish connecting a connector?; choose Continue connecting. You'll then be sent to dbt Charts Platform to sign in (if you aren't already) and to the consent screen described below. Approving returns you to Claude.

  4. Back in Claude, open the connector's Tool permissions and switch the read-only group from Needs approval to Always allow. Claude starts every tool of a new custom connector on Needs approval, which asks you to confirm each call. Leave the write group on Needs approval: it saves, moves, and deletes boards, so you confirm each one.

On a Claude Team or Enterprise plan, only an organization owner can add a custom connector. If Add custom connector is disabled for you, ask an owner to add https://dbtcharts.com/mcp for the organization. It then appears in your connector list with a Connect button, and you sign in to dbt Charts Platform as yourself from there.

Claude connects from Anthropic's cloud, not from your device, so the server URL must be reachable from the public internet. Details and plan availability are in Anthropic's own guide: Get started with custom connectors using remote MCP.

Install for your whole Claude organization

The dbt-charts Claude plugin is for claude.ai and Cowork, where Claude has no shell: it bundles this connector with the board authoring skills (the chart and styling references, plus chart-building and board-replication workflows), so Claude follows them without being asked. It lives in the public dbt-labs/dbt-charts repository, which is a plugin marketplace.

Claude Code does not need it. In a repository with the dct command line installed, run dct init skills instead: it writes one dct skill that sends Claude Code to dct skills chart, and the agent works through the CLI with no connector or sign-in. See dct init skills.

On claude.ai and Cowork, an organization owner distributes the plugin from Organization settings → Plugins & skills. Organization sync reads only private or internal marketplace repositories, so list the public plugin from a private marketplace repository of your own. Its .claude-plugin/marketplace.json:

{
  "name": "your-org-plugins",
  "owner": {
    "name": "Your IT team"
  },
  "plugins": [
    {
      "name": "dbt-charts",
      "source": {
        "source": "git-subdir",
        "url": "dbt-labs/dbt-charts",
        "path": "plugins/dbt-charts"
      }
    }
  ]
}
  1. Choose Add → Sync from GitHub and pick that repository.
  2. On the Inventory tab, set dbt-charts to Installed by default (members can turn it off) or Required.
  3. In Organization settings → Connectors, add https://dbtcharts.com/mcp. A plugin's availability doesn't add its connector; each member then connects it and signs in to dbt Charts Platform as themselves.

Anthropic's guide covers the rest: Manage plugins for your organization.

Connect from ChatGPT

  1. In the ChatGPT desktop app, open Settings → Plugins and choose Add MCP server.
  2. Set Type to Streamable HTTP.
  3. Name it (for example, dbt Charts) and paste your server URL: your Platform origin plus /mcp, for example https://dbtcharts.com/mcp.
  4. Sign in to dbt Charts Platform (if you aren't already) and approve on the consent screen described below. ChatGPT registers itself as a client automatically, so there is no client ID or secret to fill in.

If you don't see Add MCP server, your plan or workspace permissions may not allow custom MCP servers. OpenAI's setup guide has the current steps.

ChatGPT registers through anonymous dynamic client registration (DCR) rather than Claude's client ID metadata documents. With that mechanism the app names itself, so the consent screen marks the name Unverified name beside the site your browser returns to after you approve. Continue only if that is the site you came from (for ChatGPT, chatgpt.com).

What the connector can do

The connector exposes fifteen tools. Hosts decide when to call them; this is what each one does and what it's allowed to touch:

Tool What it does Checked against
search_files Finds boards by name, title, or notes across every project you can reach, or lists all of them when no text is given. With kind, searches a project's meta.yml files, dbt models, or config files instead and returns the matching lines Your board access for boards; project membership for other files
read_file Reads one file from a project, such as a meta.yml or a model's schema.yml, or one of your drafts Your board access for a board file; any other file is read as a project member. A dbt profiles.yml outside the board folders is never shown
write_file Saves a file in a project, such as a board at charts/finance/revenue.yml. Each write is one commit on the project's dbt Charts branch. Overwriting an existing file needs the hash read_file returned, so a board changed since it was read is not overwritten Needs the dashboards:write scope, and edit access to the board's folder
move_file Moves or renames a board, rewriting links to it. Moving a draft into a folder is how it gets saved Same as write_file, on both the source and the destination
delete_file Deletes a board Same as write_file
describe_board Lists a board's charts, queries, and variables Your board access
render_board Renders a stored board, or a whole board of YAML the host authors on the fly, and saves that YAML as a private draft Your board access, or your query permission on any connection the YAML touches
execute_sql Runs a board's named query, or direct SQL, against a connected source Your query permission on that source
list_skills Lists dbt Charts' authoring guides (board-building workflows, chart-layout patterns) Nothing when no project is named. Naming a project also lists that project's own skills, and needs your access to that project
get_skill Reads one skill's full guide by name Same as list_skills
list_diagnostic_codes Lists the error and warning codes a render can report, optionally by level Nothing; the registry is the same for everyone
get_diagnostic_code Explains one diagnostic code and how to fix it Nothing
list_comments Lists the comment threads on a board: the quoted text, the chart or block it sits on, replies, and whether it is resolved. Open threads unless asked for resolved or all Needs the comments:read scope, and your access to the board
post_comment Starts a thread on a board by naming a chart or block (owner) and the words to quote, or answers a thread by its id. The quote must be in the owner's title, subtitle, or prose; a quote it cannot find is refused Needs the comments:write scope, and your access to the board. The comment is yours
resolve_comment Resolves a thread Needs the comments:write scope. Only the thread's author or a board editor may resolve

execute_sql returns its rows to the AI as CSV bounded at about 25,000 tokens. You see nothing from it directly: the AI answers with a chart it renders through render_board. The tool has no row-limit argument: the AI writes LIMIT and OFFSET in the SQL, and a result that was cut says so.

Each board result from search_files or describe_board names its project's sources: the data sources you may query there, each with its SQL dialect (or its type, when the dialect is only known at run time). A source you have no query permission on is left out. When the project has a default source, it is marked default: true and the AI may omit source. A failed execute_sql names the source it ran on.

Queries are statement-guarded, row-capped, and time-limited. The connector asks for no administration scope: those are the scopes the Platform API requires to change members, project settings, and warehouse connections (the ones dct cloud asks for), and no tool here uses them. Clicking a chart or a title in a rendered board's widget opens the board, or its draft, in the dbt Charts Platform editor. A board built entirely from inline rows (a type: values query, the shape another AI tool's results arrive in) touches no data connection at all, so it renders even for a user whose organization has no warehouse connection configured yet.

Boards over uploaded files cannot be authored from Claude or ChatGPT yet: an inline render_board YAML that queries a project's file source (a csv/json/parquet source declared in your project's dbt_charts.yml, with no warehouse connection behind it) is refused. That data is still visible through search_files/describe_board/render_board on any stored board that already queries it; only an on-the-fly board over it, authored live in the chat, is not yet supported. Build that board in the Platform editor or in chat inside dbt Charts Platform itself instead.

The tool list is the same for every user. If you call a tool your permissions don't cover, you get an error naming what was denied rather than a hidden tool.

Saving boards

A board the AI builds with render_board from YAML is saved as a draft: a private file only you can open, shown in the result as a link to the dbt Charts editor. It is not part of your project until you keep it. The AI revises the same draft when you ask for changes, rather than creating a new one each time.

To keep a board, ask the AI to save it to a folder, for example "save this to finance". The AI moves the draft there (or writes the board directly) and gives you the saved board's link. The save is a commit on the project's dbt Charts branch, or on your own change branch when the project uses branch mode. The AI saves a board only when you ask. You can also open the draft's link and save it from the editor.

Saving needs the dashboards:write scope and edit access to the folder. A connector you added before this scope existed does not have it. A write call then fails with an error naming the scope, and the board is still rendered but not kept as a draft. Disconnect the connector and connect it again to grant the scope. A user with the Viewer role renders boards but cannot keep drafts.

The comment tools use the same service as the comments on a board page, so a comment posted here notifies and shows up exactly as one typed in the browser. A connector you added before the comment scopes existed has to be disconnected and connected again to grant them; a call then fails with an error naming the scope. The same threads are available over the Comments API.

Seeing what the connector reaches

A page of search results is only a sample of your boards, so every search_files result also says what the connection can reach:

  • scope lists every organization the connector may reach and, under each, its projects. A project's ref is <organization>/<project>, the same path its URL uses, so two projects with the same name in different organizations are told apart.
  • total is the number of boards that matched across all pages, after your board access is applied. The last page has no next.
  • projects is an optional argument that limits a search to the projects you name, as ref values taken from scope. Leave it out to search everything the connector reaches. A ref that names no project you can reach is an error, not an empty page, and the error does not say whether the project exists.

Connecting sends you to dbt Charts Platform to approve the client. The consent screen shows which account you're signed in as and asks which organizations the connector may reach. All organizations is checked by default, and it includes organizations you join later, so an organization you create or join afterward is reachable with no reconnecting. To limit the connector, open Choose specific organizations, uncheck the all box, and check only the organizations you want; it then reaches just those, and a new organization stays out of reach until you reconnect and add it. When you reconnect, the screen starts from the current choice. The shared demo organization is never listed, and the connector cannot reach it.

Below the organizations, the screen lists what the connector will be able to do:

  • View your boards and the data they show.
  • Run SQL directly against your connected warehouse, marked Sensitive.
  • Save, move, and delete boards in the folders you can edit, marked Sensitive.

Running SQL reaches your data directly, even though nothing it returns is written anywhere. Approve a connector the way you'd approve any tool that can see your data. Approve and connect grants every scope listed; Cancel grants nothing. If a connector you connected earlier listed administration scopes, it keeps them until you disconnect it under See and revoke access below and connect again.

The consent screen: the requesting client, an all-organizations box checked by default with a Choose specific organizations disclosure, and each scope on its own line

What the connector may access

The scopes you grant are a ceiling, never a widening. A connector acting for you can reach at most what you can already reach in dbt Charts Platform: each call re-checks your own access grants against the specific project and source it resolves to. Granting the warehouse-query scope to a user who doesn't hold query permission on a source grants nothing on that source, and the write scope grants nothing in a folder you cannot edit.

Queries the connector runs are attributed in your warehouse's job history with opaque per-user and per-request labels, so an administrator can answer "who ran that query" without any personal data appearing in warehouse metadata.

See, change, and remove access

In dbt Charts, open Account Settings → Connected Apps. It shows one card for each client with active access to your account, whether Claude, ChatGPT, or anything else you've authorized, with the organizations it reaches, the scopes it holds, and when its token was issued.

The Connected Apps page: a card for each authorized client showing its organizations, its scopes, and the Edit organizations and Disconnect buttons

Edit organizations changes which organizations a client reaches: all of them, including ones you join later, or only the ones you check. The change takes effect on the client's next call, and you don't reconnect or reauthorize anything. The scopes stay as you granted them.

Disconnect removes a client from every organization at once: its tokens are invalidated at that moment, and its next call fails. Reconnecting is the same paste-and-consent flow from scratch.

After revoking: the list is empty and the client's next call is refused