> For the complete documentation index, see [llms.txt](/llms.txt). This page is also available as markdown at this URL or via `Accept: text/markdown`.

<!-- coalesce-llms-txt-directive -->

<!-- vale Coalesce.FirstPerson = NO -->

Connect your AI assistant to Coalesce Catalog through the Model Context Protocol (MCP). Your assistant can search catalog metadata, look up assets by ID, list the columns of a table, traverse lineage, update asset descriptions, create glossary terms, and answer data questions in natural language from Claude Desktop, Cursor, Dust, or any MCP-compatible client.

For the hosted Catalog AI Assistant polling API instead of MCP tools, see [AI Assistant API][].

## What Is MCP?

The Model Context Protocol is an open standard that lets AI assistants connect to external data sources and tools. With Coalesce MCP, your assistant reads the same catalog search and metadata that powers Coalesce Catalog, without switching out of your chat or IDE. When you allow write access, it can also create glossary terms, and update the Read Me of tables, dashboards, and glossary terms and the description of columns, with the same permissions and review process as an edit in Catalog.

Ask your assistant a question such as _"Find all customer tables owned by the `{your-team-name}` team"_ and get results grounded in your catalog.

## Before You Begin

You need:

1. A **Coalesce Catalog** account with **MCP Server Access** turned on. It's off by default: an Admin turns it on in **Settings > MCP**.
2. An **MCP-compatible client**. This page covers Claude Desktop, Cursor, and Dust.

Coalesce MCP uses OAuth. When your client connects to the server URL, it opens a browser so you can sign in to Coalesce and authorize access. You no longer generate or paste a Catalog API token for MCP.

:::warning[API Token Authentication Is Deprecated]
Static Catalog API token authentication for MCP is deprecated and will be removed in a future release. Existing token-based configurations still work for now, but use OAuth for new setups and migrate existing clients when you can.
:::

## API Endpoints

Use the MCP server URL that matches your Catalog region:

- **EU:** `https://api.castordoc.com/mcp/server`
- **US:** `https://api.us.castordoc.com/mcp/server`

## Set Up Claude Desktop

Add the Coalesce MCP server to the Claude Desktop configuration file. Claude Desktop connects through `mcp-remote`, which handles the OAuth sign-in.

:::tip[Claude Custom Connectors]
You can also add the endpoint from **API Endpoints** as a custom connector in Claude. On Claude Team and Enterprise plans, an organization Owner must add the custom connector before members can connect it with their own Coalesce sign-in. See [Get started with custom connectors using remote MCP][].
:::

### 1. Create or Edit Your Configuration File

Choose either direct file or using the MCP server.

#### Direct File Access

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

#### Through Claude Desktop Settings

1. Navigate to **Claude Settings > Developer**.
2. Click **Edit Config**.

### 2. Add the Coalesce MCP Server

Add a `coalesce-catalog` entry to `mcpServers` using the endpoint from **API Endpoints** that matches your region. When Claude Desktop starts, `mcp-remote` opens a browser so you can sign in to Coalesce and authorize access.

```json title="EU endpoint configuration"
{
  "mcpServers": {
    "coalesce-catalog": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.castordoc.com/mcp/server"]
    }
  }
}
```

```json title="US endpoint configuration"
{
  "mcpServers": {
    "coalesce-catalog": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.us.castordoc.com/mcp/server"]
    }
  }
}
```

### 3. Restart Claude Desktop

Quit and reopen Claude Desktop so it loads the updated configuration. On first connection, complete the OAuth sign-in in your browser.

### 4. Test the Connection

Ask Claude: _"Can you search for `{your-data-topic}` tables in Coalesce?"_

## Set Up Cursor

Add the Coalesce MCP server by editing your local MCP configuration file.

### 1. Open Cursor Settings

In Cursor, go to **Tools & MCP** > **New MCP server**.

### 2. Configure the MCP Server

Create or edit `~/.cursor/mcp.json`. Add a `Catalog` entry using the endpoint from **API Endpoints** that matches your region. Cursor prompts you to sign in to Coalesce through your browser when it connects to the server.

```json title="EU endpoint configuration"
{
  "mcpServers": {
    "Catalog": {
      "url": "https://api.castordoc.com/mcp/server"
    }
  }
}
```

```json title="US endpoint configuration"
{
  "mcpServers": {
    "Catalog": {
      "url": "https://api.us.castordoc.com/mcp/server"
    }
  }
}
```

### 3. Restart Cursor

Restart Cursor so it picks up the new MCP configuration. When prompted, complete the OAuth sign-in to authorize access.

### 4. Verify in Cursor Agent

Open Cursor Agent and ask: _"Find tables with `{your-data-topic}` data in Coalesce"_

## Set Up Dust

Connect Catalog MCP from your Dust workspace tools settings. For a custom Dust app that polls the Catalog AI Assistant API instead, see [Dust Integration][].

### 1. Access Dust Workspace Settings

1. Navigate to your Dust workspace.
2. Go to **Spaces** > **Tools** > **Add Tools**.

### 2. Add a New MCP Connection

1. Click **Add Tools** > **Add MCP Server**.
2. Set **URL** to the EU or US endpoint from **API Endpoints**.
3. For **Authentication**, choose **OAuth**, then sign in to Coalesce in the browser window to authorize access.

### 3. Save the Connection

Change name and tool settings if needed, then save changes.

### 4. Add the MCP Server to a Dust Agent

1. Go to **Chat**.
2. Create or select an existing **Agent** > **Edit Agent**.
3. Go to **Knowledge & Tools** > **Add Tools**.
4. Add the Catalog MCP.
5. Click **Test & Save**.

In any Dust conversation, your agent can now query Catalog. For example: _"@your-agent Search Catalog for `{your-data-topic}` tables tagged as `{your-tag}`"_

## Authorizations

The MCP server uses OAuth. When your client connects to the server URL, it opens a browser for you to sign in to Coalesce and authorize access, then manages the session for you.

With OAuth, the MCP server enforces the same role-based access control as the platform for each signed-in user. Your assistant only sees the assets that user is allowed to see in Catalog, including search results, lineage, tags, teams, and users. We strongly encourage OAuth for this reason.

Static Public API token authentication is deprecated. Existing token-based configurations still work, but they will stop working in a future release. Token authentication does not apply per-user role-based access control: it returns every resource the token can access through the Public API. Migrate to OAuth when you can.

### Read and Write Access

When you authorize a client, the consent screen lists the permissions the client requests:

- **Read access** is always granted. Your assistant can search and read the assets you can see in Catalog.
- **Write access** is optional and not selected by default. It's listed only when the client requests it. Select it to let your assistant update descriptions and create glossary terms on your behalf.

Write access never extends your permissions. Updating a description or creating a glossary term requires the **Contributor** role or above, and each update follows the same rules as an edit in Catalog, including [Read Me Content Review][]. Users with the **Viewer** role can select write access, but their assistant can't update descriptions or create terms.

To add or remove write access later, reconnect the client and change your selection on the consent screen. Removing write access also removes it from the tokens the client already holds.

API tokens are read-only: the deprecated token method never updates descriptions or creates terms.

## Available Tools

The Coalesce MCP server exposes 16 tools for catalog search, asset lookup, table columns, metadata reads, description updates, and glossary term creation, grouped below. Your assistant only sees the tools your connection can use: `update_asset_description` and `create_term` require write access and the Contributor role or above. `get_description_templates` requires the Contributor role or above, and `get_company_context` is only available to Admins.

### Search Tools

These tools use the same search engine as Coalesce Catalog AI search. Each call returns at most 30 results, even when a higher `limit` is requested.

| Tool                | Purpose                    | Key Inputs                                                                                              | Result Limit             |
| ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------ |
| `search_tables`     | Find data warehouse tables | `query` required, `optionalFilters` with `name`, `ownerName`, or `tag`, `limit`, `truncate_description` | Default 10, capped at 30 |
| `search_dashboards` | Find BI dashboards         | `query` required, `optionalFilters` with `name`, `ownerName`, or `tag`, `limit`, `truncate_description` | Default 10, capped at 30 |
| `search_columns`    | Find specific columns      | `query` required, `optionalFilters` with `name` or `tag`, `limit`, `truncate_description`               | Default 20, capped at 30 |
| `search_terms`      | Search business glossary   | `query` required, `optionalFilters` with `name`, `ownerName`, or `tag`, `limit`, `truncate_description` | Default 10, capped at 30 |

The `name` filter matches the exact asset name. `truncate_description` defaults to `true` and cuts descriptions in the results at 500 words. Your assistant sets it to `false` when it needs the full text.

### Asset Lookup Tool

`get_assets` reads assets by ID. Your assistant uses it to get the details of assets it already found, such as a search result or a lineage node, and to move up to their parents, such as the table, schema, and database of a column. To find an asset by name, your assistant uses the search tools instead.

| Tool         | Purpose                                      | Inputs                                                                      | Result Limit             |
| ------------ | -------------------------------------------- | --------------------------------------------------------------------------- | ------------------------ |
| `get_assets` | Read assets by ID, in any mix of asset types | `assets` required: a list of 1 to 25 assets, each with an `id` and a `type` | Up to 25 assets per call |

Each asset type returns references to its parents. A reference has an `id`, a `name`, and a `type`, so your assistant can pass it back to `get_assets`.

| Asset Type         | Where the ID Comes From                                             | Parent References             |
| ------------------ | ------------------------------------------------------------------- | ----------------------------- |
| `TABLE`            | `search_tables`, lineage nodes, a column's `table`                  | `database`, `schema`          |
| `COLUMN`           | `search_columns`, lineage nodes                                     | `database`, `schema`, `table` |
| `DASHBOARD`        | `search_dashboards`, lineage nodes, a dashboard field's `dashboard` | `folder`                      |
| `DASHBOARD_FIELD`  | `get_field_lineage` nodes                                           | `dashboard`                   |
| `DASHBOARD_FOLDER` | A dashboard's `folder`, or a folder's `parentFolder`                | `parentFolder`                |
| `DATABASE`         | The `database` of a table, column, or schema                        | None                          |
| `SCHEMA`           | The `schema` of a table or column                                   | `database`                    |
| `TERM`             | `search_terms`, a term's `parentTerm`                               | `parentTerm`                  |

The response has two lists:

- `results`: The assets found, in the requested order. Tables, columns, dashboards, and terms return the same fields as a search result, plus their parent references, a link to the asset in Catalog, and a link to the asset in its source when available. Databases and schemas return their name, description, and warehouse. Dashboard folders return their name, path, and source.
- `notFound`: The requested assets that don't exist or that you can't access in Catalog.

Descriptions are cut at 500 words. To read the full description of a table, column, dashboard, or term, your assistant uses `get_asset_description`.

`get_assets` follows the same access rules as the search tools: with OAuth, it only returns the assets you can see in Catalog. It's available with read access, to every role.

### Table Columns Tool

`get_table_columns` lists the columns of one table, in their warehouse order. Your assistant uses it to read the actual schema of a table, for example before writing SQL, instead of guessing column names. To find columns across tables, your assistant uses `search_columns` instead.

| Tool                | Purpose                     | Inputs                                                                                    | Result Limit                                         |
| ------------------- | --------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `get_table_columns` | List the columns of a table | `tableId` required, `limit`, `cursor`, `nameContains`, and `includeDescriptions` optional | Default 200 columns per page, capped at 500 per page |

- `tableId`: The ID of the table, from `search_tables`, a lineage node, or a column's `table`.
- `nameContains`: Keeps only the columns whose name contains this text, ignoring case. A table can have more than a thousand columns, so your assistant uses it to find specific columns instead of reading every page.
- `includeDescriptions`: Defaults to `false`. Set it to `true` to also return the descriptions of each column.
- `cursor`: The `nextCursor` of the previous call, to get the next page. Leave it empty for the first page.

The response has four fields:

- `table`: A reference to the table, with its `id`, `name`, and `type`.
- `columns`: The columns of the page. Each column returns its `id`, `name`, `dataType`, whether it's nullable `isNullable`, a primary key `isPrimaryKey`, or flagged as personal data `isPii`, and the labels of its `tags`. With `includeDescriptions`, each column also returns its `description`, written in Catalog, and its `externalDescription`, synced from your warehouse or another source, or `null` when the source has none. Both are cut at 500 words. To read the full description of a column, your assistant uses `get_asset_description`.
- `totalCount`: The number of columns that match the request, across all pages.
- `nextCursor`: The cursor of the next page, or `null` on the last page. Your assistant passes it as `cursor` until it's `null`.

Columns hidden in Catalog are left out. If the table doesn't exist, is hidden, or you can't access it, the call returns an error. If a sync changes the columns of the table between two calls, a column can be skipped or returned twice.

`get_table_columns` follows the same access rules as the search tools: with OAuth, it only returns the tables you can see in Catalog. It's available with read access, to every role.

### Catalog API Tools

These tools cover lineage traversal and other catalog metadata exposed through MCP. The lineage tools, `get_asset_lineage` and `get_field_lineage`, walk upstream and downstream relationships from a starting asset or field using the same lineage graph that powers Coalesce Catalog. Each call returns up to 100 related nodes per direction, and `depth` is capped at 10 levels.

| Tool                  | Purpose                                                                      | Inputs                                                                             | Result Limit                                                                                                                    |
| --------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `get_asset_lineage`   | Upstream or downstream lineage for a data asset such as a table or dashboard | `asset_id` required, `asset_type` required, `depth` optional, `direction` optional | `depth` defaults to 1, capped at 10. `direction` defaults to `BOTH`. Up to 100 nodes per direction, up to 200 total with `BOTH` |
| `get_field_lineage`   | Field-level lineage for a specific column or dashboard field                 | `field_id` required, `field_type` required, `depth` optional, `direction` optional | `depth` defaults to 1, capped at 10. `direction` defaults to `BOTH`. Up to 100 nodes per direction, up to 200 total with `BOTH` |
| `get_company_context` | Retrieve organizational context for the authenticated account                | None                                                                               | Returns a single company context object                                                                                         |
| `get_tags`            | Retrieve tags used to categorize data assets                                 | `ids` optional, `labelContains` optional                                           | Returns all matching tags                                                                                                       |
| `get_users`           | Get all users and their profiles                                             | None                                                                               | Returns all users in the account                                                                                                |
| `get_teams`           | Get all teams and configurations                                             | None                                                                               | Returns all teams in the account                                                                                                |

### Description Tools

These tools read and update the description you edit in Catalog: the Read Me of a table, dashboard, or glossary term, or the description of a column. The description synced from your warehouse or BI tool is returned separately and never changed. Your assistant uses the ID and asset type from a search result or from `get_assets`.

| Tool                        | Purpose                                                             | Inputs                                                                                                     | Result                                                                                                                                                                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_asset_description`     | Read the full description of an asset and whether you can update it | `assetId` required, `assetType` required: `TABLE`, `COLUMN`, `DASHBOARD`, or `TERM`                        | `description`, its version `descriptionHash`, the content Markdown can't represent `lossyContent`, whether the text is AI-generated `isDescriptionGenerated`, the synced `externalDescription` and its `externalDescriptionSource`, any `pendingReview`, and `writeMode` |
| `update_asset_description`  | Replace the description of an asset                                 | `assetId`, `assetType`, and `description` required, `expectedDescriptionHash` and `isAiGenerated` optional | `UPDATED` with the stored description, or `REVIEW_SUBMITTED` with the review ID                                                                                                                                                                                          |
| `get_description_templates` | Read your account's description templates                           | `assetType` optional: `TABLE`, `DASHBOARD`, or `TERM`. Leave it empty to get the templates of every type   | `results`, each with an `id`, a `name`, an `assetType`, and the template `content` in Markdown                                                                                                                                                                           |

`writeMode` tells your assistant what an update does:

- `DIRECT`: the update is published immediately.
- `REVIEW`: the update is submitted for approval.
- `DENIED`: you can't update this description. `writeModeMessage` explains why.
- `READ_ONLY`: this connection has no write access. `writeModeMessage` explains how to get it.

#### How Description Updates Work

- **Full replacement:** The new text replaces the whole description. Your assistant reads the description first and passes its `descriptionHash`, so the update fails if someone changed the description in the meantime. Ask your assistant to read it again and retry.
- **Read Me Content Review:** If [Read Me Content Review][] is enabled, only owners of the asset and Admins publish immediately. Other users, Stewards included, submit a change for approval, which an owner or an Admin approves or rejects in the **Task Center**. While a change is pending, nobody can update the description. Column descriptions are not reviewed.
- **Formats:** Table, dashboard, and term descriptions use Markdown, up to 30,000 characters: headings, bold, italic, strike-through, inline code, code blocks, bulleted lists, numbered lists, quotes, links, tables, and horizontal rules. Images, HTML, and task lists aren't supported. Column descriptions are plain text, stored exactly as sent, up to 2,700 characters.
- **Content Markdown can't represent:** Some formatting from the Catalog editor has no Markdown equivalent, such as images, underlined text, text alignment, and links to Catalog assets. `get_asset_description` lists it in `lossyContent`, and an update removes it permanently. Your assistant should ask you before overwriting such a description. You can also edit it in Catalog instead.
- **Restrictions:** Glossary terms synced from an external source can only be changed in that source. An update can't clear a description: empty descriptions are rejected.
- **AI-generated text:** When your assistant writes or rewrites the text, it sets `isAiGenerated` and Catalog marks the description as AI-generated. On a table's columns, **Remove all AI Assistant description** removes AI-generated column descriptions.
- **History:** Updates appear in the asset history and notifications like an edit in Catalog, attributed to the signed-in user.

#### Description Templates

Description templates are the suggested structures your team defines in Catalog for the Read Me of tables, dashboards, and glossary terms. Columns have no templates.

Templates are optional. Before writing a description with `update_asset_description` or `create_term`, your assistant checks whether a template exists for that asset type and, if so, asks you whether to follow it. When it follows a template, it fills the sections with facts about the asset instead of copying the placeholder text.

### Glossary Term Tool (Known as Knowledge Pages)

`create_term` creates a glossary term. Your assistant calls `search_terms` first, to avoid creating a duplicate and to find the ID of the parent term when you want the new term nested.

| Tool          | Purpose                | Inputs                                                                       | Result                                                           |
| ------------- | ---------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `create_term` | Create a glossary term | `name` required, `description`, `parentTermId`, and `isAiGenerated` optional | The term `id`, `name`, `slug`, and a link to the term in Catalog |

- **Permissions:** Creating a term requires write access and the Contributor role or above. You become an owner of the new term. API tokens can't create terms.
- **Description:** Markdown, in the same format as `update_asset_description`. When your assistant writes or rewrites the text, it sets `isAiGenerated` and Catalog marks the description as AI-generated.
- **Parent term:** The parent term must be in your Catalog account. Glossary terms synced from an external source can't have terms nested under them.

## Troubleshooting

### Connection Issues

If you see **Failed to connect to MCP server**, check the following:

1. If sign-in shows **MCP access is not enabled for your workspace**, ask an Admin to turn on **MCP Server Access** in **Settings > MCP**.
2. Reconnect the server so the client reopens the OAuth sign-in, then complete authorization in the browser.
3. Confirm the endpoint URL matches your Catalog region, EU or US.
4. Test network connectivity to your Catalog API host.
5. If you still use the deprecated API token method, verify the token is valid and not expired. See [Getting Your Catalog API Keys][] for rotation steps if the token was revoked or replaced.

### MCP Calls Return 401 Unauthorized

Reconnect the server so the client reopens the OAuth sign-in, then complete authorization in the browser to restore access.

If you still use the deprecated API token method, generate a replacement in **Settings > API**, replace the token in your MCP client configuration, and restart the client. See [Getting Your Catalog API Keys][] for expiration notices and rotation impact on other integrations.

### AI Not Using Tools

If your assistant answers from general knowledge instead of calling MCP tools:

- Be explicit in the prompt, for example _"Search Coalesce Catalog MCP for…"_ using the server name from your config.
- Ask about specific asset types: tables, columns, dashboards, or glossary terms.
- Mention owners, teams, or tags by name when you know them.

### AI Cannot Update Descriptions or Create Terms (Known as Knowledge Pages)

If your assistant can't update a description or create a glossary term:

- If `update_asset_description` or `create_term` is missing, reconnect the server and select **Write access** on the consent screen. You also need the Contributor role or above. API tokens can't update descriptions or create terms.
- If the update fails because a change is pending approval, an owner of the asset or an Admin must approve or reject it in the **Task Center** first.
- If the update fails because the description changed since your assistant read it, ask your assistant to read the description again and retry.
- If the term is synced from an external source, change its description in that source. Your assistant also can't nest a new term under it.

## FAQ

### Does This Work With All AI Assistants?

Any MCP-compatible client can connect with custom configuration. This page documents Claude Desktop, Cursor, and Dust.

### What Data Does the AI Assistant See?

The assistant can search and read catalog metadata: table and column names, descriptions, owners, tags, lineage, and glossary terms available to your Coalesce user, or to your API token if you still use the deprecated token method.

### Can the AI Assistant Change Catalog Content?

Only descriptions and new glossary terms, and only when you select **Write access** on the consent screen. Description updates follow your role, asset ownership, and Read Me Content Review, and appear in the asset history. Creating a term requires the Contributor role or above. See [Description Tools](#description-tools) and [Glossary Term Tool](#glossary-term-tool-known-as-knowledge-pages).

## Resources

- [Model Context Protocol][]
- [Getting Your Catalog API Keys][]
- [Catalog Public API documentation][]

## What's Next?

- [Getting Your Catalog API Keys][]
- [AI Assistant API][]
- [Dust Integration][]

[Getting Your Catalog API Keys]: /docs/catalog/developer/getting-your-api-keys
[Catalog Public API documentation]: /docs/catalog/developer/catalog-apis/public-api
[Model Context Protocol]: https://modelcontextprotocol.io/
[AI Assistant API]: /docs/catalog/developer/ai-assistant-api
[Dust Integration]: /docs/catalog/developer/dust-integration
[Read Me Content Review]: /docs/catalog/collaborate/approval-process
[Get started with custom connectors using remote MCP]: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp
