> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/analyze-with-ai/mcp-setup.md).

# MCP setup

Chord MCP lets Claude answer questions about your store's data. Once it's connected, you can ask questions like *"how many returning customers viewed a cart before purchasing?"* in plain English. Claude pulls the answer from your Chord warehouse, writing and running the SQL for you.

This guide walks you through connecting Chord MCP to Claude in about five minutes. The recommended path needs no coding. A config-file setup for engineers is covered at the end.

**What you'll need**

* A Claude account (Free, Pro, Max, Team or Enterprise)
* A Chord account with access to your organization's data

{% hint style="info" %}
**For best results, use Claude Opus, or the most capable model available on your plan.** Answering a data question takes several steps: searching your schema, checking saved queries and your organization's conventions, drafting SQL and validating it before it runs. More capable models complete these steps faster and more reliably, especially for complex questions like cohort analysis, churn breakdowns or year-over-year comparisons. Smaller models handle simple lookups well but may time out on multi-step queries.

To change your model, use the model picker near the message box before you start the conversation.
{% endhint %}

## What is Chord MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude connect securely to outside tools and data. Chord MCP is Chord's hosted MCP server. It gives Claude a read-only view of your Chord data warehouse.

When you ask a data question, Claude uses Chord MCP to:

* Look up the right tables and saved queries in your warehouse
* Apply your organization's conventions, such as how you define revenue or which test orders to exclude
* Write the SQL, run it and explain the answer

The connection is **read-only.** Claude can look at your data and answer questions, but it can't change or delete anything.

## Set up Chord MCP (recommended)

The easiest way to connect is through Claude's custom connectors. Everything happens in the Claude interface, with no terminal or config files.

{% hint style="info" %}
**On Team and Enterprise plans,** only an organization Owner can add a custom connector for the whole organization. If you don't see the option to add one, ask your Claude workspace Owner to add Chord MCP using the steps below, then skip to step 3.
{% endhint %}

### 1. Open your connector settings

In Claude, go to **Settings > Connectors**.

* On **Pro or Max** plans, this is under **Customize > Connectors**. Click **+**, then **Add custom connector**.
* On **Team or Enterprise** plans, an Owner adds it under **Organization settings > Connectors**: click **Add**, hover over **Custom** and select **Web**.

### 2. Add the Chord MCP server URL

When prompted for the remote MCP server URL, enter:

```
https://mcp.chord.co/mcp
```

Leave the optional advanced settings (OAuth client ID and secret) blank. Click **Add**.

### 3. Connect and sign in

Find **Chord** in your list of connectors and click **Connect**. A browser window opens for you to sign in to Chord and approve access. This is a standard OAuth sign-in: Claude never sees your password, and you can revoke access at any time from your connector settings.

### 4. Turn it on in a conversation

Start a new chat. Click **+** (or **Search and tools**) near the message box, choose **Connectors** and make sure **Chord** is turned on for the conversation.

## Ask your first question

Type a question in plain English. Claude recognizes it as a data question and uses Chord MCP automatically. Try one of these:

* *"How many orders did we have last month?"*
* *"What was our gross revenue in Q1, broken down by month?"*
* *"Show me our top 10 products by revenue this year."*
* *"How many new customers did we acquire last quarter versus the quarter before?"*
* *"What's our average order value over the last 90 days?"*

Claude finds the right tables, applies your warehouse conventions, writes the SQL, runs it and explains the result. It usually cites which tables and definitions it used, so you can check the number.

{% hint style="info" %}
**Be specific.** "Gross revenue" and "net revenue" can mean different things. Say which one you want, and Claude uses the matching definition.
{% endhint %}

## What Claude can do with Chord MCP

Claude picks the right tool for each question, so you don't need to call these yourself. Here's what's available:

| Capability        | What it does                                                                                                          |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Run query**     | Runs read-only SQL and returns the rows                                                                               |
| **Search schema** | Finds which tables exist in your warehouse and what they contain                                                      |
| **Saved views**   | Checks whether a trusted, pre-built query already answers your question                                               |
| **Past queries**  | Finds similar questions you've asked before, to use as examples                                                       |
| **Instructions**  | Applies your organization's standing rules, such as revenue definitions, test-order exclusions and segmentation logic |
| **Documentation** | Answers "how do I…" questions about Chord                                                                             |
| **Preview table** | Shows a few rows of a table for a quick check                                                                         |
| **Tenants**       | Lets you see and switch between the Chord organizations you belong to                                                 |

{% hint style="info" %}
**Working across several organizations?** If you have access to more than one Chord organization, ask Claude something like *"switch to the \[organization name] organization."* It routes your questions to that warehouse for the rest of the conversation.
{% endhint %}

## Troubleshooting

**My question times out or never finishes**

Complex questions take several rounds of schema lookup, SQL drafting and validation. Switch to Claude Opus using the model picker near the message box, since it resolves ambiguous questions in fewer steps. On any model, it also helps to break a big question into smaller ones, for example "first show me cancellations by week, then break down the top week by reason".

**Claude isn't using Chord, or says it can't reach the data**

Make sure the Chord connector is turned on for your current conversation, in the **+** or **Search and tools** menu. Connectors are turned on per chat.

**The connector won't connect**

Chord MCP connects from Claude's cloud, not from your computer, so `https://mcp.chord.co/mcp` needs to be reachable over the public internet. This works out of the box for the hosted Chord endpoint. If your team runs Chord behind a corporate firewall or VPN, your network admin may need to allowlist Anthropic's IP ranges.

**I signed in but still get permission errors**

Your Chord account needs access to your organization's data. Check with your Chord admin that your account has the right permissions, then disconnect and reconnect the connector.

**I need to change the connection**

To edit a custom connector, remove it (connector settings > the three-dot menu > **Remove**) and add it again with the updated details.

## Advanced: connect with a config file

Engineers can connect Chord MCP through Claude Desktop's local configuration instead of custom connectors. This uses the `mcp-remote` shim to bridge Claude Desktop to the hosted server.

{% hint style="info" %}
**Requirements:** Node.js (for `npx`) and, for the installer script, `jq`. macOS and Linux only.
{% endhint %}

**Option A: one-line installer**

```shell
curl -fsSL https://raw.githubusercontent.com/chordcommerce/ask-chord/main/install.sh | bash -s -- --client claude-desktop
```

This adds a Chord MCP entry to your `claude_desktop_config.json`. Fully quit Claude Desktop (**Cmd+Q** on macOS) and reopen it. The first connection opens a browser window for OAuth sign-in.

**Option B: edit the config by hand**

Open your Claude Desktop config file:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Linux:** `~/.config/Claude/claude_desktop_config.json`

Add Chord under `mcpServers`:

```json
{
  "mcpServers": {
    "ask-chord": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.chord.co/mcp"]
    }
  }
}
```

Save the file, fully quit and reopen Claude Desktop, and complete the browser sign-in the first time it connects.

{% hint style="info" %}
The config-file method is separate from custom connectors and only works in Claude Desktop. For most people, custom connectors are simpler, and they also work in Claude on the web and in Cowork.
{% endhint %}

Before you set up recurring or automated use, read [MCP limits and usage guidelines](/analyze-with-ai/mcp-limits-and-usage-guidelines.md).

## Questions?

Reach out to your Chord contact or email <help@chord.co>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/analyze-with-ai/mcp-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.