MCP Integration

Connect your AI assistant to Coalesce Catalog through the Model Context Protocol (MCP). Your assistant can search catalog metadata, traverse lineage, 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.

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 API access.
2. A Catalog API token from Settings > API. See Getting Your Catalog API Keys for generation and rotation steps. Use Read Only scope when you do not need write access. Treat the token as a secret.
3. An MCP-compatible client. This page covers Claude Desktop, Cursor, and Dust.

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

Claude Desktop does not support quick MCP setup for API token-based authentication yet, so you edit the configuration file manually.

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. Replace YOUR_API_TOKEN_HERE with your Catalog API token.

EU endpoint configuration

{
  "mcpServers": {
    "coalesce-catalog": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.castordoc.com/mcp/server",
        "--header",
        "Authorization: YOUR_API_TOKEN_HERE"
      ]
    }
  }
}

US endpoint configuration

{
  "mcpServers": {
    "coalesce-catalog": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.us.castordoc.com/mcp/server",
        "--header",
        "Authorization: YOUR_API_TOKEN_HERE"
      ]
    }
  }
}

3. Restart Claude Desktop

Quit and reopen Claude Desktop so it loads the updated configuration.

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. Replace YOUR_API_TOKEN_HERE with your Catalog API token.

EU endpoint configuration

{
  "mcpServers": {
    "Catalog": {
      "url": "https://api.castordoc.com/mcp/server",
      "headers": {
        "Authorization": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

US endpoint configuration

{
  "mcpServers": {
    "Catalog": {
      "url": "https://api.us.castordoc.com/mcp/server",
      "headers": {
        "Authorization": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

3. Restart Cursor

Restart Cursor so it picks up the new MCP configuration.

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, type Bearer Token, then set Bearer Token to YOUR_API_TOKEN_HERE.

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 Public API Token authentication. OAuth is not yet supported.

The server does not enforce role-based access control inside Catalog. It returns every resource your API token can access through the Public API, including search results, lineage, tags, teams, and users.

Available Tools

The Coalesce MCP server exposes 10 tools for catalog search and metadata reads, grouped below.

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, name, ownerName, tag, limit	Default 10, capped at 30
search_dashboards	Find BI dashboards	query required, name, ownerName, tag, limit	Default 10, capped at 30
search_columns	Find specific columns	query required, name, tag, limit	Default 20, capped at 30
search_terms	Search business glossary	query required, name, ownerName, tag, limit	Default 10, capped at 30

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	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	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

Troubleshooting

Connection Issues

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

1. Verify the API token is valid and not expired. See Getting Your Catalog API Keys for rotation steps if the token was revoked or replaced.
2. Confirm the endpoint URL matches your Catalog region, EU or US.
3. Test network connectivity to your Catalog API host.

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.

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 API token.

What Happens If the Token Expires?

MCP calls return 401 Unauthorized. Generate a replacement in Settings > API, update the Authorization value in your MCP client config, and restart the client. See Getting Your Catalog API Keys for expiration notices and rotation impact on other integrations.

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