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

  1. Open Claude's Add Custom Connector form.
    ​

    If the link above does not open the Add Custom Connector form, open Claude Web in your browser (https://claude.ai), go to Customize > Connectors, click Add, and select Add custom connector.

  2. Fill in the Foundational MCP server details and click Continue:
    ​

    1. MCP Name: Foundational.
      ​

    2. Remote MCP Server URL: https://mcp.foundational.io/mcp

  3. Verify the authentication configuration and click Add:
    ​

    1. Authentication: Make sure Always Required is selected.
      ​

    2. OAuth Client: Select No client ID - Register one automatically.

  4. Authenticate and connect. If Claude does not show the Foundational MCP as connected, click Connect. Complete the authentication with Foundational.
    ​

  5. Verify. After successful authentication, the Foundational connector shows the list of tools provided by Foundational MCP.
    ​

  6. For detailed steps, see Connect to remote MCP servers in the Model Context Protocol documentation.

Connect Claude Desktop

Foundational is a remote MCP server, so add it as a custom connector rather than a local server. For background, see Get started with custom connectors using remote MCP in the Anthropic Claude Help Center.

  1. Open the Claude app and go to Settings (⌘,) > Connectors.
    ​

  2. Click Add > Add custom connector.
    ​

  3. Enter the Foundational MCP details and click Continue:
    ​

    1. MCP Name: Foundational.
      ​

    2. MCP Server URL: https://mcp.foundational.io/mcp.

  4. Verify the authentication settings. Claude automatically detects the correct settings; confirm these are the selected options, then scroll down and click Add:
    ​

    1. Authentication: Always required.
      ​

    2. OAuth Client: No client ID - register one automatically

  5. Claude opens the Foundational connector page. Click Connect and complete the authentication flow in your browser.
    ​

  6. After authentication, Claude redirects you to the Foundational connector page. If authentication succeeded, you see the list of tools shown in this screenshot:

Connect Claude Code (CLI)

Foundational is a remote MCP server using the streamable HTTP transport protocol. To add it to Claude Code, follow these steps:

  1. Add Foundational MCP to your Claude Code. Open a terminal and run this command:
    ​

    claude mcp add --transport http foundational https://mcp.foundational.io/mcp

  2. Authenticate against Foundational:
    ​

    1. Open Claude Code by running claude in your terminal.
      ​

    2. Inside Claude Code, run the /mcp command to open the MCP management panel.
      ​

    3. You should see foundational under Local MCPs or User MCPs, marked as failed or unauthenticated.
      ​

    4. Select the foundational MCP from the list and press Return (⏎).
      ​

    5. Select the Authenticate option. This opens your web browser to complete the authentication against Foundational.
      ​

  3. Verify:
    ​

    1. After successful authentication, go back to Claude Code and run the /mcp command again.
      ​

    2. You should now see the foundational MCP in the list marked as
      ​ ✔ connected · 40 tools.
      ​

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.

VS Code

There are two options to connect to VS Code.
​

Option 1: 1-click installation (recommended)

  1. Copy the line below, paste it into your browser's address bar, and press Return (⏎):

vscode:mcp/install?%7B%22name%22%3A%22foundational%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.foundational.io%2Fmcp%22%7D

If you use VS Code Insiders, replace vscode: with vscode-insiders:

2. Click Install.


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

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


a) Complete the login to Foundational in your browser.


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

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

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

Connect ChatGPT / Codex

  1. Open ChatGPT and go to Settings > Plugins > MCPs, then click Add server.
    ​

  2. Fill in the form:
    ​

    1. Set a Name (for example, Foundational).
      ​

    2. Set Type to Streamable HTTP.
      ​

    3. Set Server URL to https://mcp.foundational.io/mcp
      ​

    4. Click Save.
      ​

  3. Authenticate with Foundational. Find the Foundational MCP server in the MCPs list, click Authenticate, and complete the authentication in your browser.

ChatGPT can only reach servers on the public internet. This works with Foundational's hosted MCP server; it does not apply to self-hosted or air-gapped deployments.

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

Related Articles
Did this answer your question?