Skip to main content

Connect Foundational MCP to GitHub Copilot

Add the Foundational MCP server to Copilot Chat in VS Code, the Copilot CLI, and the Copilot coding agent, including the bearer token the coding agent requires.

Connect Foundational MCP to GitHub Copilot

Foundational runs a hosted Model Context Protocol (MCP) server at https://mcp.foundational.io/mcp. Connecting it to GitHub Copilot gives Copilot your end-to-end column-level lineage, table and column definitions, ownership and metadata, and downstream consumers such as dashboards and ML models — so Copilot can reason about what a schema change breaks outside the repository it has open.

Copilot is really three products with three different MCP configurations. This article covers all of them: Copilot Chat in VS Code, the Copilot CLI, and the Copilot coding agent (the cloud agent that opens pull requests).

Important: the Copilot coding agent and Copilot code review do not support remote MCP servers that use OAuth. For those surfaces you must use Foundational's machine-to-machine authentication with a bearer token. See Connect the Copilot coding agent below.

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.

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 a GitHub Copilot license. MCP support requires agent mode in VS Code.
    ​

  • To configure the coding agent, you need repository admin rights and a Foundational API token. See Create API Tokens.

Connection details

  • Server URL: https://mcp.foundational.io/mcp
    ​

  • Transport: Streamable HTTP ("type": "http")
    ​

  • Authentication (VS Code, CLI): OAuth 2.0 with Dynamic Client Registration
    ​

  • Authentication (coding agent): bearer token in the format CLIENT_ID:SECRET_KEY
    ​

  • Suggested name: foundational

Connect Copilot Chat in VS Code

Option 1: Use the guided flow

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

  2. Choose HTTP (HTTP or Server-Sent Events).
    ​

  3. Enter the server URL:
    ​

    https://mcp.foundational.io/mcp

  4. Name the server foundational.
    ​

  5. Choose Global to make it available in every workspace, or Workspace to write it to .vscode/mcp.json for this repository only.
    ​

  6. VS Code starts the authentication flow. Click Allow when prompted, then Open, and complete the Foundational login in your browser.

Option 2: Edit mcp.json

For a workspace-level server, create or edit .vscode/mcp.json. For a user-level server, run MCP: Open User Configuration from the Command Palette.

Note that VS Code uses servers as the top-level key, not mcpServers:
​

{
  "servers": {
    "foundational": {
      "type": "http",
      "url": "https://mcp.foundational.io/mcp"
    }
  }
}

Because Foundational authenticates over OAuth rather than a static secret, .vscode/mcp.json is safe to commit — it contains no credentials, and each engineer signs in as themselves the first time they use it.

Verify

  1. Run MCP: List Servers from the Command Palette and confirm foundational is listed and running.
    ​

  2. Open Copilot Chat, switch to Agent mode, and click the tools icon. The Foundational tools should appear in the list.
    ​

  3. Ask a question only Foundational can answer, such as: "Using Foundational, list the downstream consumers of the dim_customers table."

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.

Connect the Copilot CLI

  1. Add the server:
    ​

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

  2. Confirm it was registered:
    ​

    copilot mcp list
    copilot mcp get foundational

  3. Start Copilot CLI and complete the authentication prompt for Foundational when it appears.

The CLI stores servers in ~/.copilot/mcp-config.json. You can edit that file directly instead:
​

{
  "mcpServers": {
    "foundational": {
      "type": "http",
      "url": "https://mcp.foundational.io/mcp",
      "tools": ["*"]
    }
  }
}

The tools array controls which tools are enabled. Use ["*"] for all of them, or list specific tool names to narrow the surface. You can also set this at add time with --tools.

Connect the Copilot coding agent

The Copilot coding agent runs on GitHub's infrastructure and cannot complete a browser OAuth flow, so it requires a Foundational API token passed as a bearer header.

Step 1: Create a Foundational API token

Follow Create API Tokens to generate a client ID and secret key. The MCP server expects them combined as CLIENT_ID:SECRET_KEY.

Step 2: Store it as a Copilot secret

  1. In your repository, go to Settings > Environments and open (or create) the copilot environment.
    ​

  2. Add a secret named COPILOT_MCP_FOUNDATIONAL_TOKEN with the value CLIENT_ID:SECRET_KEY.

Only secrets and variables prefixed with COPILOT_MCP_ are visible to MCP configurations. A secret named anything else resolves to an empty string, and the connection fails with an authentication error.

Step 3: Add the MCP configuration

  1. In your repository, go to Settings > Copilot > MCP servers.
    ​

  2. Paste this into the MCP configuration field and save:
    ​

    {
      "mcpServers": {
        "foundational": {
          "type": "http",
          "url": "https://mcp.foundational.io/mcp",
          "headers": {
            "Authorization": "Bearer $COPILOT_MCP_FOUNDATIONAL_TOKEN"
          },
          "tools": ["*"]
        }
      }
    }

Step 4: Verify

Assign the coding agent an issue that requires lineage context — for example, "Rename user_id to customer_id in the orders model; use Foundational to check downstream consumers first." Then open the agent's session log from the pull request and confirm the Foundational tool calls appear.

The coding agent uses configured MCP tools autonomously and does not ask for approval. The token you supply defines exactly what it can see, so scope the Foundational account behind that token to the access the agent actually needs.

What Foundational changes about how Copilot works

Impact analysis before a schema change

Copilot sees the repository it has open. Foundational supplies everything past its edge: the dashboards, downstream tables, ML features, and operational databases that read the columns being changed.

  • "Before renaming this column, check Foundational for downstream consumers and list anything I can't fix in this repo."
    ​

  • "Which dashboards break if I drop legacy_status from orders?"

Pull request review with real lineage

  • "Review this diff and flag any column removals that Foundational shows as having downstream consumers."

For lineage-aware checks that run automatically on every pull request without a Copilot license, see Continuously Check Your Pull Requests with Foundational CI.

Governance and privacy checks

  • "List tables with columns tagged pii and their downstream consumers."
    ​

  • "Does this change join pii-tagged columns into a table tagged public?"

Troubleshooting

VS Code does not pick up the server

The most common cause is the wrong top-level key. VS Code uses "servers"; the Copilot CLI and the coding agent use "mcpServers". Copying a config between them without changing the key silently produces a server that never loads. Run MCP: List Servers to confirm what VS Code actually sees.

The coding agent fails to connect with an authentication error

The coding agent does not support OAuth for remote MCP servers, so it must use a bearer token. Check that: the secret name starts with COPILOT_MCP_; the secret lives in the repository's copilot environment; and the value is the full CLIENT_ID:SECRET_KEY pair, not just the secret key.

Copilot Chat ignores the Foundational tools

MCP tools are only available in Agent mode, not Ask or Edit mode. Switch modes in the chat view, then open the tools picker and confirm Foundational is enabled. Naming the server in your prompt ("use Foundational to…") also makes tool selection more reliable.

Connection fails behind a corporate proxy or firewall

Allow outbound HTTPS to mcp.foundational.io. The Copilot coding agent runs on GitHub's infrastructure, so it can only reach a Foundational deployment that is available on the public internet — self-hosted and air-gapped deployments work with VS Code and the CLI from inside your network instead. See Allowing IP access to Foundational.

Related articles

Related Articles
Did this answer your question?