MCP Integration

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:

A Coalesce Catalog account with MCP Server Access turned on. It's off by default: an Admin turns it on in Settings > MCP.
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.

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.

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

Navigate to Claude Settings > Developer.
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.

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

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.

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

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

Navigate to your Dust workspace.
Go to Spaces > Tools > Add Tools.

2. Add a New MCP Connection

Click Add Tools > Add MCP Server.
Set URL to the EU or US endpoint from API Endpoints.
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

Go to Chat.
Create or select an existing Agent > Edit Agent.
Go to Knowledge & Tools > Add Tools.
Add the Catalog MCP.
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:

If sign-in shows MCP access is not enabled for your workspace, ask an Admin to turn on MCP Server Access in Settings > MCP.
Reconnect the server so the client reopens the OAuth sign-in, then complete authorization in the browser.
Confirm the endpoint URL matches your Catalog region, EU or US.
Test network connectivity to your Catalog API host.
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 and Glossary Term Tool.

What Is MCP?​

Before You Begin​

API Endpoints​

Set Up Claude Desktop​

1. Create or Edit Your Configuration File​

Direct File Access​

Through Claude Desktop Settings​

2. Add the Coalesce MCP Server​

3. Restart Claude Desktop​

4. Test the Connection​

Set Up Cursor​

1. Open Cursor Settings​

2. Configure the MCP Server​

3. Restart Cursor​

4. Verify in Cursor Agent​

Set Up Dust​

1. Access Dust Workspace Settings​

2. Add a New MCP Connection​

3. Save the Connection​

4. Add the MCP Server to a Dust Agent​

Authorizations​

Read and Write Access​

Available Tools​

Search Tools​

Asset Lookup Tool​

Table Columns Tool​

Catalog API Tools​

Description Tools​

How Description Updates Work​

Description Templates​

Glossary Term Tool (Known as Knowledge Pages)​

Troubleshooting​

Connection Issues​

MCP Calls Return 401 Unauthorized​

AI Not Using Tools​

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

FAQ​

Does This Work With All AI Assistants?​

What Data Does the AI Assistant See?​

Can the AI Assistant Change Catalog Content?​

Resources​

What's Next?​