Introduction

Foundational runs a hosted Model Context Protocol (MCP) server at https://mcp.foundational.io/mcp. Connecting it to VS Code gives GitHub Copilot Chat's agent mode direct access to your end-to-end column-level lineage, table and column definitions, ownership and metadata, usage and cost signals, and the code behind your data assets. Before it suggests a change to a dbt model, Airflow DAG, or Spark job, Copilot can check the upstream sources, downstream dependencies, and existing definitions involved, so it writes safer code and avoids breaking changes.

This article covers two ways to connect VS Code: the install link (recommended), and manual setup from the Command Palette. Both work in VS Code and VS Code Insiders. Each user connects VS Code themselves.

Looking for a different tool?

See Use Foundational MCP with your AI tools for the full client list, use cases, and machine-to-machine authentication.
To use Foundational with the Copilot CLI or the Copilot coding agent, see Connect Foundational MCP to GitHub Copilot.

Before you begin

You need an active user account in the Foundational app. The MCP server authorizes against your Foundational identity and returns only the assets your account can already see.
You need GitHub Copilot in VS Code. You use the Foundational tools through Copilot Chat's agent mode.
Your network must allow outbound HTTPS to mcp.foundational.io.

Connection details

Both setups use the same values:

Server URL: https://mcp.foundational.io/mcp
Transport: Streamable HTTP. When VS Code asks for the server type, choose HTTP.
Authentication: OAuth 2.0 with Dynamic Client Registration. You don't need to create a client ID, secret, or API token.
Suggested name: foundational

Connect with the install link (recommended)

Copy the link below, paste it into your browser's address bar, and press Return (⏎) or Enter. When your browser asks to open VS Code, allow it.
```
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
```
Note: Using VS Code Insiders? Replace vscode: at the start of the link with vscode-insiders:.
VS Code opens the Foundational MCP server's install page. Click Install.
VS Code authenticates with Foundational. If it asks to allow the authentication, click Allow and then Open, and complete the Foundational sign-in in your browser.

Connect manually

Use this setup if your organization blocks install links.

Open the Command Palette (⇧⌘P on macOS, Ctrl+Shift+P on Windows and Linux) and run MCP: Add Server.

You can also start the same flow from Chat: Open Customizations > MCP Servers > Add Server.
Choose HTTP (HTTP or Server-Sent Events) and enter the server URL:
```
<https://mcp.foundational.io/mcp>
```
Enter the server ID foundational.
Select Global, then Copilot Global. VS Code saves the server to ~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json when you setCOPILOT_HOME), outside your project, so it's available in every workspace. If Copilot Global isn't offered, check the Copilot harness requirements.
Note: Don't choose the workspace .vscode/mcp.json or the user-profile mcp.json destination. VS Code keeps them for compatibility only and labels them deprecated in this flow.
VS Code authenticates with Foundational. If it asks to allow the authentication, click Allow and then Open, and complete the Foundational sign-in in your browser.

For more detail, see Add MCP servers in VS Code in the VS Code documentation.

Share the Foundational MCP connection with your team

To share the server with your team, save it to a .mcp.json file at the root of your workspace and commit it. The guided flow offers this destination only when the experimental chat.mcp.workspaceRootConfig.enabled setting is on. You can also create the file by hand. It holds no credentials, because each person signs in with their own Foundational account:

{

  "mcpServers": {

    "foundational": {

      "type": "http",

      "url": "https://mcp.foundational.io/mcp"

    }

  }

}

Verify the connection

Run MCP: List Servers from the Command Palette. VS Code lists foundational as running.
Open Copilot Chat, switch to Agent mode, and click the tools icon. The Foundational tools appear in the list.

The most direct check is to ask a question only Foundational can answer, such as:

"Using Foundational, list the downstream consumers of the dim_customers table."

If Copilot answers with real table, column, or dashboard names from your environment, the connection is working.

What to ask Copilot once connected

"Where does the fct_user_sessions table get its data from?"
"Which dashboards use the dim_products table?"
"Before I change this dbt model, which models and dashboards depend on it?"
"Are there any expensive tables that are unused?"
"List all tables containing columns tagged with pii and show their downstream consumers."

Troubleshooting

The install link does nothing

Some browsers and locked-down machines block links that open a desktop app. Use the manual setup above instead.

VS Code doesn't pick up a server you added to mcp.json

VS Code uses servers as the top-level key in mcp.json, not mcpServers. A configuration copied from another tool without changing the key never loads. Run MCP: List Servers to confirm what VS Code sees.

Copilot Chat doesn't use the Foundational tools

VS Code limits how many tools can be active in a single chat request. Foundational exposes a large tool set, so if you have several MCP servers connected, use the tools picker to enable only the Foundational tools you need for the task.

Foundational fails to load with Node.js or npx errors

These errors come from the npx mcp-remote bridge, not from Foundational. VS Code connects to Foundational directly, so you don't need the bridge. Remove any mcp-remote entry for Foundational and add the server with one of the setups above.

The sign-in fails or loops

Confirm you can sign in to the Foundational app (https://app.foundational.io) in the same browser. The MCP server authorizes your Foundational user account, so an expired session or a different single sign-on (SSO) account is the usual cause. If you can't sign in to the Foundational app, ask your IT or data administrator to invite you to Foundational.

Connection fails behind a corporate proxy or firewall

Allow outbound HTTPS to mcp.foundational.io. See Allowing IP access to Foundational.

Connect Foundational MCP to VS Code