Skip to main content

Use Foundational MCP with your AI tools

Updated yesterday

Introduction

The Model Context Protocol (MCP) Server, introduced by Anthropic, lets AI assistants and other applications access APIs and contextual data that are not directly available to the core AI model. It acts as a secure gateway or translator.

For example, an MCP server connected to a tool such as GitHub can translate a natural language request—“List my open pull requests”—into the correct API call and return the matching information.

Use the Foundational MCP server to connect your AI tools to the full context of your data environment. The server provides:

  • End-to-end lineage

  • Usage information for models and dashboards

  • Code definitions for tables, models, and upstream operational database

  • Ownership and metadata details

  • Other metadata related to your data assets

Use cases

This section describes typical uses cases.

Use AI to refactor and write data engineering pipelines

Use AI to safely modify or create data pipelines with Foundational context.

When you modify or create data pipelines (for example, dbt models, Airflow DAGs, or Spark jobs),

AI tools connected to the Foundational MCP server can access critical context. Before suggesting code changes, the AI can query the MCP server to understand upstream sources, downstream dependencies (dashboards, other tables, ML models), column data types, and existing definitions for the tables involved.

This context helps the AI write safer and more accurate code, prevent breaking changes, ensure consistency with existing logic, and suggest optimizations based on table usage patterns identified by Foundational.

Ask AI questions about your data stack

Use natural language to explore your data without opening lineage graphs or searching documentation.

Ask questions such as:

  • “Where does the fct_user_sessions table get its data from?”
    ​

  • “Which dashboards use the dim_products table?”
    ​

  • “Who owns the customer_pii_data dataset?”
    ​

  • “Show me the description for the order_status column.”

The Foundational MCP server gives the AI access to lineage, metadata, and usage information from your Foundational workspace so it can answer these questions accurately and instantly.

Use AI to find and implement cost reduction suggestions

Use AI to explore cost-saving recommendations detected by Foundational.

Foundational automatically identifies cost-saving opportunities in your data warehouse (see the article Cost Savings Recommendations).

Connect your AI tool through the MCP server and ask questions such as:

  • “Are there any expensive tables that are unused?”
    ​

  • “Explain why this pipeline is flagged for running too frequently.”
    ​

  • “Show me the lineage for this table recommended for deletion to confirm it has no downstream consumers.”

Find potential security and privacy issues

Use AI to find potential data governance and compliance issues.

Ask the AI questions such as:

  • “List all tables containing columns tagged with pii and show their downstream consumers.”
    ​

  • “Are there any data pipelines joining columns tagged with pii and public?”

The MCP server gives the AI access to the necessary lineage context from Foundational so it can identify potential compliance issues quickly.

Configure Foundational MCP

The Foundational MCP server requires a user account in the Foundational app.

When you configure the MCP server, use the following JSON configuration:
​

{
  "mcpServers": {
    "foundational-io": {
      "url": "https://mcp.foundational.io/mcp"
    }
  }
}


To configure a remote MCP server JSON file, see Other Clients in this article.

Connect Claude Web

  1. To connect to Claude Web, follow the instructions in the Anthropic Claude Help Center in the article Connect to Remote MCP Servers.
    ​

  2. Enter the URL https://mcp.foundational.io/mcp as the integration’s remote MCP server URL.

Connect Claude Desktop

To connect to Claude Desktop follow the instructions in the Anthropic Claude Help Center in the article Connect to local MCP servers.

  1. Click Connect apps.
    ​

  2. Click Add custom connector.
    ​

  3. Enter Foundational MCP details and click Add.
    ​

  4. In the Connected apps screen, click Connect.
    ​

  5. You should now see that Foundational MCP is connected.
    ​

Cursor

Configure MCP servers in a JSON file.

  1. Open the file from MCP under Cursor Settings, then select Add new server.
    ​

  2. Copy and paste the JSON configuration shown above.

For detailed steps, go to the Cursor website and locate the section Using ‘mcp.json’ in the article Model Context Protocol (MCP).

VS code

For detailed steps, go to the Visual Studio website and see the article Use MCP servers in VS Code.

Other clients

Most MCP clients do not yet support the latest MCP specification. To connect to the Foundational MCP server, use a bridge client such as npx mcp-remote.

We recommend this approach and use it in the examples below.

When you use npx mcp-remote or another bridge client, make sure it runs on the fixed port 8818:

{
  "mcpServers": {
    "foundational-io": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.foundational.io", "8818"]
    }
  }
}

Install Node.js and the mcp-remote package

To use a remote MCP server, install both Node.js and the mcp-remote package.

If Node.js is not already installed, go to nodejs.org and download the LTS (Long-Term Support) version for your operating system.

Use Node.js version 22 or higher.

After installing Node.js, open your terminal or command prompt and install the mcp-remote package globally:

npm install -g mcp-remote

Machine-to-machine authentication

Use machine-to-machine authentication for automated systems, CI/CD pipelines, or server-to-server integrations where interactive OAuth flows are not practical.

This method lets you embed Foundational MCP capabilities into backend services, automated workflows, or custom AI deployments without requiring user interaction.

When to use machine-to-machine authentication

  • Deploy MCP servers in production environments
    ​

  • Integrate Foundational into automated data pipelines
    ​

  • Build custom AI tools that need programmatic access
    ​

  • Run server-side applications that cannot use OAuth flows

Configure machine-to-machine authentication

  1. Generate API keys.

    Follow the instructions in the article Create API Tokens.
    ​

  2. Configure the MCP server.

    Add the bearer token in the format CLIENT_ID:SECRET_KEY.
    ​

    {
      "mcpServers": {
        "foundational-io": {
          "type": "streamable-http",
          "url": "https://mcp.foundational.io/mcp",
          "headers": {
            "Authorization": "Bearer CLIENT_ID:SECRET_KEY"
          }
        }
      }
    }

IMPORTANT: For desktop applications such as Claude Desktop, Claude Code, or Cursor, continue to use the regular OAuth authentication flow.

Machine-to-machine authentication is designed only for headless, automated, or server-side deployments.

Troubleshooting MCP Server Errors

If the MCP server fails to load, you’ll see an error in the UI or logs.

MCP Server Error

Open the logs to check details.
For Claude on macOS logs go to:
/Users//Library/Logs/Claude/mcp-server-foundational-io.log

The sections below describe common errors and how to fix them.

TransformStream Error

Problem

The MCP server fails to start. The logs show an error such as:
​

ReferenceError: TransformStream is not defined

or a Node.js version warning:

npm WARN cli npm v10.9.2 does not support Node.js v16.18.1. This version of npm supports the following node versions: ^18.17.0 || >=20.5.0.

Cause

An outdated Node.js version is installed. The Foundational MCP server requires Node.js v22 or later to run correctly.

Fix

  1. List all installed Node.js versions:
    ​

    nvm list

  2. Uninstall versions earlier than v22. For example:
    ​

    nvm uninstall v16.18.1

  3. Install or switch to Node.js v22 or later.

  4. After updating Node.js, restart your AI tool or terminal session.

NPX Cache Issues

Problem

The MCP server fails to load or connect. You may see one of these errors:

  • command not found: mcp-remote

  • Error: Cannot find module 'mcp-remote'

  • ENOENT: no such file or directory

Cause

NPX caches packages globally to improve performance. If the mcp-remote package updates or the cache becomes corrupted, NPX may use an outdated or broken version instead of fetching the latest one.

Fix

  1. Clear the NPX cache:
    ​

    npx clear-npx-cache

  2. Reinstall the mcp-remote package:

    npm install -g mcp-remote

  3. Restart your AI tool (Claude Desktop, Cursor, VS Code, etc.).

The MCP server should now load correctly.

NPM Package Download SSL Errors

Problem

You see SSL errors when running npx mcp-remote or npm install -g mcp-remote, such as:

  • unable to get local issuer certificate

  • self signed certificate in certificate chain

  • Package installation fails with SSL/TLS errors

Cause

Corporate proxies or firewalls can intercept HTTPS connections to the npm registry (registry.npmjs.org). This causes npm to fail SSL certificate verification when downloading packages, preventing npx from fetching the mcp-remote package needed to run the MCP server.

Fix

IMPORTANT: This disables SSL verification only for npm package downloads. For a secure setup, ask your IT team to configure npm to use your corporate CA certificate or proxy settings.

  1. Temporarily disable SSL verification:
    ​

    npm config set strict-ssl false

  2. Reinstall or run the package:

    npm install -g mcp-remote

  3. Re-enable SSL verification after installation:
    ​

    npm config set strict-ssl tru

Related Articles
Solution architecture
Did this answer your question?