Skip to main content

Use Foundational MCP with your AI tools

Introduction

The Model Context Protocol (MCP) Server, introduced by Anthropic, lets AI agents and other applications access tools and contextual data that are not directly available to the core AI model. It acts as a secure gateway, providing a standard interface for tool invocation and resource sharing. This allows vendors and users to extend AI agents' and LLMs' capabilities and knowledge.

For example, connecting GitHub’s MCP server to your AI agent allows it, and the LLM, to translate a natural language request such as "List my open pull requests" into the correct tool invocations, which normally translate to API requests behind the scenes, and return the requested 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 databases
    ​

  • 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

Foundational's MCP server address is:
​

https://mcp.foundational.io/mcp


It uses the Streamable HTTP transport protocol. Some clients need an explicit definition of the transport type, for these set the type to http.

No API key or token is needed for interactive use. After you configure the MCP server, your AI tool directs you to Foundational to complete an authentication process.

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

Find your tool below for step-by-step instructions.

Connect Agentforce

For setup steps, see Connect Foundational MCP to Agentforce.

Connect ChatGPT / Codex

For setup steps, see Connect Foundational MCP to ChatGPT and Codex.

Connect Claude

For setup steps, see Connect Foundational MCP to Claude.

Cursor

There are two options to connect to Cursor.
​

Option 1: 1-click installation (recommended)

  1. Use this link to add Foundational MCP to Cursor. Cursor opens an Install MCP Server dialog. Click Install to add Foundational MCP.
    ​

  2. Foundational MCP now appears in the MCPs list. Click Authenticate and complete the login to Foundational in your browser.
    ​

  3. After successful authentication, Cursor redirects you and shows the Foundational MCP as connected and ready to use.
    ​

Option 2: Manual setup (may be required in some enterprise setups)

  1. From Cursor's Agents window, go to Customize > MCPs and click New MCP Server. This opens Cursor's mcp.json config file in the editor.
    ​

  2. Edit the file to include the Foundational MCP server config:
    ​

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

You may already have other MCP servers listed in mcp.json. If so, add the Foundational MCP server under the existing mcpServers object, alongside the other servers.
​

For detailed steps, see Model Context Protocol (MCP) in the Cursor documentation.

Connect Devin

For setup steps, see Connect Foundational MCP to Devin.

Connect GitHub Copilot

For setup steps, see Connect Foundational MCP to GitHub Copilot.

Connect Microsoft 365 Copilot

For setup steps, see Connect Foundational MCP to Microsoft 365 Copilot.

Connect Snowflake Cortex

For setup steps, see Connect Foundational MCP to Snowflake Cortex.

VS Code

There are two options to connect to VS Code.
​

Option 1: 1-click installation (recommended)

  1. Click the following link for VS Code, or VS Code Insiders.
    ​

  2. Click Install.
    ​

  3. Authentication: VS Code tries to authenticate with Foundational.

If prompted to allow the authentication, click Allow, then click Open and complete the login to Foundational in your browser.

Option 2: Manual setup

  1. Open the Command Palette and run MCP: Add Server.
    ​

  2. Choose HTTP and enter:
    ​

    https://mcp.foundational.io/mcp

  3. Name the MCP server ("foundational" is a reasonable choice).
    ​

  4. Authentication: VS Code tries to authenticate with Foundational.

    1. If prompted to allow the authentication, click Allow, then click Open.

    2. Complete the login to Foundational in your browser.

For detailed steps, see Use MCP servers in VS Code.

Other clients

Clients supporting remote MCP over streamable HTTP

Any client that supports remote MCP servers over streamable HTTP can connect directly. Point it at https://mcp.foundational.io/mcp and choose OAuth authentication.

Legacy clients: via the mcp-remote bridge

Older clients that predate remote MCP support cannot connect directly. For those clients only, use the npx mcp-remote bridge, which runs locally and forwards to the Foundational server.

Try connecting directly first. The bridge adds a Node.js dependency and is the source of most setup problems. See Troubleshooting MCP Server Errors below.

The second argument is the local port mcp-remote uses for its OAuth callback. It is not part of the Foundational server address:
​

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

Install Node.js and the mcp-remote package
​

To use the bridge, 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

Use to:

  • 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 Creating API Token.
    ​

  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

The errors below all come from the npx mcp-remote bridge and its Node.js dependency.

If you hit them, first check whether your tool supports connecting directly to https://mcp.foundational.io/mcp. Direct connection removes the bridge and these failure modes entirely.

MCP server fails to load


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

Open the logs to check details.
​

For Claude on macOS, logs go to /Users/<username>/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 mcp-remote bridge requires Node.js v22 or later to run correctly. The Foundational server itself needs no Node.js. Connecting directly avoids this entirely.
​

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 true

Useful Links

Related Articles
Did this answer your question?