Skip to main content

Connect Foundational MCP to Factory.ai (Droid)

Add the Foundational MCP server to Factory.ai Droid with one command, so Droid can check column-level lineage and downstream impact before it changes a data pipeline.

Connect Foundational MCP to Factory.ai (Droid)

Foundational runs a hosted Model Context Protocol (MCP) server at https://mcp.foundational.io/mcp. Connecting it to Factory.ai gives Droid access to your end-to-end column-level lineage, table and column definitions, ownership and metadata, and downstream consumers such as dashboards and ML models. Droid can then reason about the blast radius of a data change before it writes the code, rather than after the pipeline breaks.

Setup takes one command. Factory discovers Foundational's authorization server and registers an OAuth client automatically, so there is nothing to create in advance.

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 the Droid CLI installed and signed in to Factory.
    ​

  • Your machine must allow outbound HTTPS to mcp.foundational.io.

Connection details

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

  • Transport type: http (Streamable HTTP)
    ​

  • Authentication: OAuth 2.0 with Dynamic Client Registration — leave OAuth enabled and do not pass an Authorization header
    ​

  • Suggested name: foundational

Option 1: Add Foundational from the command line (recommended)

  1. Add the server:
    ​

    droid mcp add foundational https://mcp.foundational.io/mcp --type http

  2. Authenticate. Start Droid and open the interactive MCP manager:
    ​

    /mcp


    Foundational appears with a needs authentication status. Select it to start the browser sign-in flow, then complete the Foundational login.
    ​

  3. Confirm the connection:
    ​

    droid mcp list


    The foundational entry should read connected.

Do not pass --no-oauth. That flag is for servers authenticated by a static header; Foundational uses the OAuth flow for interactive use.

Option 2: Edit mcp.json directly

Factory reads MCP servers from mcp.json at three levels:

  • User: ~/.factory/mcp.json — personal servers, available in every project
    ​

  • Folder: .factory/mcp.json in an ancestor directory — shared across nested projects
    ​

  • Project: .factory/mcp.json in the repository root — team servers, committed to the repo

Because Foundational uses OAuth rather than a static secret, the project-level file is safe to commit: it contains no credentials, and each engineer authenticates as themselves the first time they use it.

Add Foundational under mcpServers:
​

{
  "mcpServers": {
    "foundational": {
      "type": "http",
      "url": "https://mcp.foundational.io/mcp",
      "disabled": false
    }
  }
}

If the file already contains other servers, add foundational alongside them inside the existing mcpServers object rather than replacing it.

Then run /mcp inside Droid to complete the browser sign-in.

Useful configuration options

Factory supports several optional fields that are worth knowing for a large MCP server:

  • disabledTools — an array of tool names to exclude. Use this to narrow Foundational's tool surface if you want Droid to focus on lineage lookups only.
    ​

  • timeout — tool invocation timeout in milliseconds. Raise it if deep lineage traversals on very large graphs time out.
    ​

  • connectTimeout — initial handshake timeout in milliseconds.
    ​

  • disabled — set to true to keep the entry but temporarily stop loading it.

For example:
​

{
  "mcpServers": {
    "foundational": {
      "type": "http",
      "url": "https://mcp.foundational.io/mcp",
      "timeout": 60000,
      "connectTimeout": 15000
    }
  }
}

Verify the connection

Run droid mcp list and confirm foundational reads connected rather than needs authentication, connecting, or failed.

Then give Droid a task only Foundational can answer:

  • "Using Foundational, list every downstream consumer of the dim_customers table."
    ​

  • "Who owns fct_orders, and which dashboards read from it?"

If Droid returns real table, column, and dashboard names from your environment, the connection is working.

What Foundational changes about how Droid works

Impact analysis before Droid edits a pipeline

Droid is strong at multi-file refactors inside a repository, and blind to everything outside it. Foundational supplies the missing half: the dashboards, downstream tables, ML features, and operational databases that read the columns Droid is about to change.

  • "Rename user_id to customer_id across this dbt project. Check Foundational for downstream consumers first and list anything you cannot fix in this repo."
    ​

  • "Before you finish, confirm with Foundational that nothing reads the columns this diff removes."

Large migrations and cleanup

  • "Find the pipelines Foundational reports as building unused, expensive tables, and prepare a deprecation plan."
    ​

  • "Backfill column descriptions in this schema from the definitions Foundational already has."

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

The server stays on "needs authentication"

Run /mcp inside Droid and select Foundational to restart the browser sign-in. Confirm you can sign in to the Foundational app in the same browser profile — the MCP server authorizes your Foundational user account, so an expired session or a different SSO account is the usual cause. If the flow still does not complete, remove and re-add the server:
​

droid mcp remove foundational
droid mcp add foundational https://mcp.foundational.io/mcp --type http

The server shows "failed"

Check that --type http was set. Without it, Factory defaults to stdio and tries to run the URL as a local command, which always fails. Confirm the entry in mcp.json reads "type": "http", and that the URL is exactly https://mcp.foundational.io/mcp with no trailing slash.

Your edits to mcp.json have no effect

The same server name can be defined at the user, folder, and project levels, and organization-managed servers take precedence over all of them. If a foundational entry already exists at a higher-precedence level, your local edit is ignored. Run droid mcp list to see which definition is in effect.

Connection fails behind a corporate proxy or firewall

Allow outbound HTTPS to mcp.foundational.io. If your Foundational deployment is self-hosted or restricted by IP allowlist, make sure the machine running Droid is inside the permitted range. See Allowing IP access to Foundational.

Automated and headless use

For CI/CD pipelines or automated Droid runs where a browser sign-in is not practical, use machine-to-machine authentication. Generate credentials as described in Create API Tokens, then add the server with a bearer header and OAuth disabled:
​

droid mcp add foundational https://mcp.foundational.io/mcp --type http \
  --header "Authorization: Bearer CLIENT_ID:SECRET_KEY" --no-oauth

Or, in mcp.json, using Factory's environment variable expansion so the secret never lands in a committed file:
​

{
  "mcpServers": {
    "foundational": {
      "type": "http",
      "url": "https://mcp.foundational.io/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer ${FOUNDATIONAL_MCP_TOKEN}"
      }
    }
  }
}

Droid expands ${NAME} against your shell environment when it connects, so set FOUNDATIONAL_MCP_TOKEN to CLIENT_ID:SECRET_KEY in your CI secret store.

For interactive use on a developer machine, stay with the OAuth flow. Machine-to-machine tokens are intended only for headless and server-side deployments.

Related articles

Related Articles
Did this answer your question?