Skip to main content

Connect Foundational MCP to Devin

Add the Foundational MCP server to Devin cloud sessions and the Devin CLI so Devin checks column-level lineage and downstream impact before it opens a pull request.

Connect Foundational MCP to Devin

Foundational runs a hosted Model Context Protocol (MCP) server at https://mcp.foundational.io/mcp. Connecting it to Devin gives Cognition's autonomous engineer the same lineage context your data team relies on: end-to-end column-level lineage, table and column definitions, ownership and metadata, and downstream consumers such as dashboards and ML models. Devin uses that context before it opens a pull request, so a schema change it proposes accounts for consumers that live outside the repository it is working in.

This article covers both places you can add Foundational: Devin cloud sessions (through the MCP Marketplace in Settings) and the Devin CLI.

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

  • To add a custom MCP server for cloud sessions, you need permission to change your organization's Devin settings.
    ​

  • For the CLI, use Devin CLI v3000.3 or later, which stores MCP servers in dedicated configuration files.
    ​

  • Devin cloud sessions run on Cognition's infrastructure, so mcp.foundational.io must be reachable from the public internet. For self-hosted or air-gapped Foundational deployments, use the Devin CLI from inside your network instead.

Connection details

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

  • Transport: HTTP (Streamable HTTP)
    ​

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

  • Suggested name: foundational

Devin keeps its own MCP credentials. Authorizing Foundational in Claude Code, Cursor, or Windsurf does not carry over — you authenticate Devin separately.

Add Foundational to Devin cloud sessions

  1. In the Devin app, go to Settings > Connections > MCP servers.
    ​

  2. Click Add a custom MCP at the top of the page.
    ​

  3. Fill in the server details:
    ​

    1. Server Name: Foundational
      ​

    2. Short Description: Data lineage, metadata, ownership, and usage context from Foundational.
      ​

    3. Icon (optional): an emoji or an image URL.
      ​

  4. Set the Transport to HTTP (Streamable HTTP).
    ​

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

  6. Set the authentication method to OAuth. Foundational supports Dynamic Client Registration, so you do not need to supply a client ID or secret.
    ​

    Choose whether the connection is organization-wide or personal. Foundational scopes every response to the authenticating user's permissions, so a personal connection is the safer default unless your team shares a Foundational service identity.
    ​

  7. Click Save, then complete the Foundational sign-in in the browser window Devin opens.
    ​

  8. Click Test listing tools to confirm connectivity. A successful test returns the list of Foundational tools.

Add Foundational to the Devin CLI

Option 1: Add from the command line (recommended)

  1. Register the server:
    ​

    devin mcp add foundational https://mcp.foundational.io/mcp

  2. Authorize it. This opens your browser to complete the Foundational login:
    ​

    devin mcp login foundational

  3. Confirm the server is registered and authenticated:
    ​

    devin mcp list

Option 2: Edit the configuration file

Devin reads MCP servers from these files, in increasing order of precedence:

  • User: ~/.config/devin/mcp_config.json (on Windows, %APPDATA%\devin\mcp_config.json)
    ​

  • Project: .devin/mcp_config.json in the repository root — commit this to share the server with your team
    ​

  • Local override: .devin/mcp_config.local.json — gitignored, for anything you do not want committed

Add Foundational under mcpServers:
​

{
  "mcpServers": {
    "foundational": {
      "url": "https://mcp.foundational.io/mcp",
      "transport": "http"
    }
  }
}

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

Then authorize:
​

devin mcp login foundational

Verify the connection

For cloud sessions, use Test listing tools on the MCP server page in Settings.

For the CLI, run devin mcp list. The foundational entry should show a connected status rather than auth-required. Devin namespaces MCP tools as mcp__foundational__<tool>, and lists them during agent initialization.

The most direct check is to give Devin a task only Foundational can answer, such as: "Using Foundational, list the downstream consumers of the dim_customers table before you change anything." If Devin returns real table and dashboard names from your environment, the connection is working.

What Foundational changes about how Devin works

Impact analysis before a pull request

Devin's blind spot on data work is everything outside the repository it was given. Foundational closes it. Ask Devin to check lineage before it edits a model, and it can see the dashboards, downstream tables, ML features, and operational databases that depend on the columns it is about to rename or drop.

  • "Rename user_id to customer_id in this dbt model. First check Foundational for every downstream consumer and update or flag each one."
    ​

  • "Before merging, confirm with Foundational that nothing reads the columns removed in this diff."

Working through data engineering backlog

  • "Find tables Foundational reports as unused and expensive, and open a PR deprecating the pipelines that build them."
    ​

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

Governance and privacy checks

  • "List tables with columns tagged pii and their downstream consumers, then tell me which of them are exposed in a public dashboard."
    ​

  • "Check whether this new join mixes pii-tagged columns into a table tagged public."

Troubleshooting

The server shows "auth-required" or "needs authentication"

The OAuth token has not been issued yet or has expired. Re-run the login:
​

devin mcp logout foundational
devin mcp login foundational

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. For cloud sessions, reconnect from Settings > Connections > MCP servers.

"Test listing tools" fails in the Devin app

Check three things: the transport is set to HTTP (Streamable HTTP) and not SSE or STDIO; the URL is exactly https://mcp.foundational.io/mcp with no trailing slash or extra path; and the OAuth flow completed. If your Foundational deployment is self-hosted or restricted by IP allowlist, Devin's cloud infrastructure cannot reach it — use the Devin CLI from inside your network. See Allowing IP access to Foundational.

Devin does not use the Foundational tools

Confirm the server is enabled — devin mcp enable foundational on the CLI, or check that "disabled" is not set to true in mcp_config.json. Devin also tends to reach for MCP tools more reliably when the task names them, so include an instruction such as "use Foundational to check lineage first" in the session prompt or in your repository's Devin knowledge notes.

Devin sees fewer assets than expected

Foundational scopes MCP responses to the permissions of the authenticated user. If Devin is connected through a personal OAuth grant, it sees exactly what that person sees. To broaden coverage, either connect with an account that has wider access or configure the server organization-wide.

Automated and headless use

If you run Devin in a pipeline or an environment where the interactive OAuth flow is not practical, use machine-to-machine authentication instead. Generate credentials as described in Create API Tokens, then configure an Auth Header in the Devin app, or add a bearer header to mcp_config.json:
​

{
  "mcpServers": {
    "foundational": {
      "url": "https://mcp.foundational.io/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer CLIENT_ID:SECRET_KEY"
      }
    }
  }
}

Keep secrets out of committed files. Use .devin/mcp_config.local.json or an environment variable reference rather than .devin/mcp_config.json.

Related articles

Related Articles
Did this answer your question?