Skip to main content

Connect Foundational MCP to Claude

Connect the Foundational MCP server to Claude Web, Claude Desktop, and Claude Code so Claude can read your column-level lineage, metadata, and ownership.

Connect Foundational MCP to Claude

Foundational runs a hosted Model Context Protocol (MCP) server at https://mcp.foundational.io/mcp. Connecting it to Claude gives Claude direct, read-time 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. Claude answers questions about your data stack and writes safer pipeline code because it can look up the real dependency graph instead of guessing.

This article covers all three Claude surfaces: Claude Web, Claude Desktop, and Claude Code (the CLI). Setup takes about two minutes per surface and requires no API key.

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 Claude account. Custom connectors on Claude Web and Claude Desktop require a paid Claude plan; Claude Code supports MCP on all plans.
    ​

  • Your network must allow outbound HTTPS to mcp.foundational.io. For Claude Web, the connection is made from Anthropic's infrastructure, so the server must be reachable from the public internet.

Connection details

Every Claude surface uses the same values:

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

  • Transport: Streamable HTTP (set the type to http where a client asks for it)
    ​

  • Authentication: OAuth 2.0 with Dynamic Client Registration — no client ID, secret, or API token to create
    ​

  • Suggested name: foundational

Connect Claude Web

  1. Go to claude.ai and open Settings > Connectors.
    ​

  2. Click Add custom connector.
    ​

  3. Fill in the form and click Continue:
    ​

    1. Name: Foundational
      ​

    2. Remote MCP server URL: https://mcp.foundational.io/mcp
      ​

  4. Confirm the authentication settings, then click Add:
    ​

    1. Authentication: Always required
      ​

    2. OAuth Client: No client ID — register one automatically
      ​

  5. Click Connect on the Foundational connector and complete the Foundational sign-in in the browser tab that opens.
    ​

  6. Return to Settings > Connectors. The Foundational connector now lists the tools it exposes.
    ​

  7. In a new chat, open the tools menu and make sure Foundational is enabled for the conversation.

Connect Claude Desktop

Foundational is a remote MCP server, so add it as a custom connector rather than as a local stdio server. You do not need to edit claude_desktop_config.json.

  1. Open Claude Desktop and go to Settings (⌘, on macOS, Ctrl+, on Windows) > Connectors.
    ​

  2. Click Add > Add custom connector.
    ​

  3. Enter the details and click Continue:
    ​

    1. Name: Foundational
      ​

    2. MCP server URL: https://mcp.foundational.io/mcp
      ​

  4. Claude detects the authentication settings automatically. Confirm Authentication: Always required and OAuth Client: No client ID — register one automatically, then scroll down and click Add.
    ​

  5. Click Connect and complete the Foundational login in your browser.
    ​

  6. Claude returns you to the Foundational connector page, which now shows the available Foundational tools.

Connect Claude Code (CLI)

  1. Add the server. In a terminal, run:
    ​

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


    Add --scope user to make the server available in every project rather than only the current one:
    ​

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

  2. Authenticate.
    ​

    1. Start Claude Code by running claude.
      ​

    2. Run the /mcp command to open the MCP management panel. foundational appears marked failed or needs authentication — this is expected before the first sign-in.
      ​

    3. Select foundational, press Return (⏎), and choose Authenticate. Your browser opens to complete the Foundational login.
      ​

  3. Verify. Back in Claude Code, run /mcp again. foundational now reads ✔ connected with the tool count.

Verify the connection

The fastest check is to ask Claude a question only Foundational can answer. In a new conversation, try:

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

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

If Claude answers with real table, column, or dashboard names from your environment, the connection is working. If it says it has no such tool, confirm the connector is toggled on for that specific conversation.

What to ask Claude once connected

Trace lineage and impact

  • "Where does fct_user_sessions get its data from, column by column?"
    ​

  • "If I drop the legacy_status column from orders, what breaks?"
    ​

  • "Which dashboards depend on dim_products?"

Write and refactor pipeline code safely

Claude Code is at its most useful here. Before it edits a dbt model, Airflow DAG, or Spark job, it can query Foundational for the upstream sources, downstream consumers, column types, and existing definitions of every table involved — so the change it proposes accounts for consumers that live outside the repository it is working in.

  • "Refactor this dbt model, but first check Foundational for anything downstream that reads the columns I'm renaming."
    ​

  • "Add a column to this Spark job consistent with how the same field is defined upstream."

Find governance and privacy exposure

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

  • "Are any pipelines joining pii-tagged columns into publicly tagged tables?"

Investigate cost savings

  • "Are there expensive tables in our warehouse with no downstream consumers?"
    ​

  • "Show the lineage for this table flagged for deletion so I can confirm nothing reads it."

Troubleshooting

The connector stays "unauthenticated" or the login loops

Confirm you can sign in to the Foundational app in the same browser profile Claude opened. The MCP server authorizes the Foundational user account, so an expired session or a different SSO account is the usual cause. In Claude Code, run /mcp, select foundational, and choose Clear authentication (or remove and re-add the server) before retrying.

Claude says it has no Foundational tools

Connectors are enabled per conversation on Claude Web and Claude Desktop. Open the tools menu in the chat composer and switch Foundational on. On Claude Code, run /mcp and check that the server shows ✔ connected rather than failed.

"MCP server failed to load" with Node.js or npx errors

These errors come from the npx mcp-remote bridge, not from Foundational. All current Claude surfaces connect to remote MCP servers directly, so the bridge is not needed — remove any mcp-remote entry and add Foundational as a custom connector or with claude mcp add --transport http instead. If you must use the bridge on an older client, see the troubleshooting section of Use Foundational MCP with your AI tools.

Connection fails behind a corporate proxy or firewall

Allow outbound HTTPS to mcp.foundational.io. Claude Web additionally requires that the server be reachable from the public internet, which rules it out for self-hosted or air-gapped Foundational deployments — use Claude Desktop or Claude Code in those environments. See Allowing IP access to Foundational.

Automated and headless use

The OAuth flow above is for interactive use. For CI/CD pipelines, backend services, or custom agent deployments where a browser login is not practical, use machine-to-machine authentication with a bearer token in the format CLIENT_ID:SECRET_KEY. Generate the credentials as described in Create API Tokens, then see the machine-to-machine section of Use Foundational MCP with your AI tools.

For Claude Web, Claude Desktop, and Claude Code, always use the standard OAuth flow. Machine-to-machine tokens are intended only for headless and server-side deployments.

Related articles

Related Articles
Did this answer your question?