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

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

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.

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. Reconnect the server so the client reopens the OAuth sign-in, then complete authorization in the browser.
2. Confirm the endpoint URL matches your Catalog region, EU or US.
3. Test network connectivity to your Catalog API host.
4. 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.

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.

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