# Introduction The Model Context Protocol (MCP) Server, introduced by [Anthropic](https://www.anthropic.com/news/model-context-protocol), lets AI assistants and other applications access APIs and contextual data that are not directly available to the core AI model. It acts as a secure gateway or translator. For example, an MCP server connected to a tool such as GitHub can translate a natural language request—*“List my open pull requests”*—into the correct API call and return the matching information. Use the Foundational MCP server to connect your AI tools to the full context of your data environment. The server provides: - End-to-end lineage - Usage information for models and dashboards - Code definitions for tables, models, and upstream operational database - Ownership and metadata details - Other metadata related to your data assets --- # Use cases This section describes typical uses cases. **## Use AI to refactor and write data engineering pipelines** Use AI to safely modify or create data pipelines with Foundational context. When you modify or create data pipelines (for example, dbt models, Airflow DAGs, or Spark jobs), AI tools connected to the Foundational MCP server can access critical context. Before suggesting code changes, the AI can query the MCP server to understand upstream sources, downstream dependencies (dashboards, other tables, ML models), column data types, and existing definitions for the tables involved. This context helps the AI write safer and more accurate code, prevent breaking changes, ensure consistency with existing logic, and suggest optimizations based on table usage patterns identified by Foundational. **## Ask AI questions about your data stack** Use natural language to explore your data without opening lineage graphs or searching documentation. Ask questions such as: - “Where does the `fct_user_sessions` table get its data from?” ​ - “Which dashboards use the `dim_products` table?” ​ - “Who owns the `customer_pii_data` dataset?” ​ - “Show me the description for the `order_status` column.” The Foundational MCP server gives the AI access to lineage, metadata, and usage information from your Foundational workspace so it can answer these questions accurately and instantly. **## Use AI to find and implement cost reduction suggestions** Use AI to explore cost-saving recommendations detected by Foundational. Foundational automatically identifies cost-saving opportunities in your data warehouse (see the article [Cost Savings Recommendations](https://docs.foundational.io/en/articles/9997818-cost-savings-recommendations)). Connect your AI tool through the MCP server and ask questions such as: - “Are there any expensive tables that are unused?” ​ - “Explain why this pipeline is flagged for running too frequently.” ​ - “Show me the lineage for this table recommended for deletion to confirm it has no downstream consumers.” **## Find potential security and privacy issues** Use AI to find potential data governance and compliance issues. Ask the AI questions such as: - “List all tables containing columns tagged with `pii` and show their downstream consumers.” ​ - “Are there any data pipelines joining columns tagged with `pii` and `public`?” The MCP server gives the AI access to the necessary lineage context from Foundational so it can identify potential compliance issues quickly. --- # Configure Foundational MCP The Foundational MCP server requires a user account in the Foundational app. When you configure the MCP server, use the following JSON configuration: ​ ``` { "mcpServers": { "foundational-io": { "url": "https://mcp.foundational.io/mcp" } } } ``` To configure a remote MCP server JSON file, see **Other Clients** in this article. **## Connect Claude Web** 1. To connect to Claude Web, follow the instructions in the [Anthropic Claude Help Center](https://support.claude.com/en/) in the article [Connect to Remote MCP Servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers). ​ 2. Enter the URL as the integration’s remote MCP server URL. **## Connect Claude Desktop** To connect to Claude Desktop follow the instructions in the [Anthropic Claude Help Center](https://support.claude.com/en/) in the article [Connect to local MCP servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers). 1. Click **Connect apps**. ​ ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1826851680/6402aeac46ad8888862311ac1443/claude+evening+john.png?expires=1781782200&signature=f84556a01fa5999073e5a6769d2a00e7df3d15a08c4d0039cc0db53e39dd617a&req=dSglEMF7nIdXWfMW1HO4zdzRg10ZDS6RQXfVQZ0gqGumuc0pInqhwGgedybp%0ARu12%0A) 2. Click **Add custom connector**. ​ ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1826857081/f5208ca920cb9915f7f4ce04f49c/claude+add+customer+connector.png?expires=1781782200&signature=3ab0a0eab6b4249aee8d6528e7631041957a45879ec1f112ea1769c6e67ee37c&req=dSglEMF7moFXWPMW1HO4zcozhSc6uIRmuJc2fKmis9S9kVF0zEK0CDpbP3xm%0A3bn0%0A) 3. Enter Foundational MCP details and click **Add**. ​ ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1826857595/a7421747339ae3bf2efa327f3491/claude+add+foundational+collector+details.png?expires=1781782200&signature=29e70f235c54fb379b230be09e754c76cbfec9354b70a24e59a23c3652253604&req=dSglEMF7moRWXPMW1HO4zWNlQXCjh7KU9RhuXSlJmMWSWoCEG4wHWwkkAhLL%0A1iZP%0A) 4. In the **Connected apps** screen, click **Connect**. ​ ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1826858750/0c64fd3fa82b59f3b68ffbdc69e4/claude+click+connect+button.png?expires=1781782200&signature=39e908bfae66fa8261036bd070a88749b5c9459d167a9577573997e7ed917c49&req=dSglEMF7lYZaWfMW1HO4zcTsc%2FltQ8SeCgUoVrJNKfWtBDOghhGCOHvzb3xS%0AK5XY%0A) 5. You should now see that Foundational MCP is connected. ​ ![](https://downloads.intercomcdn.com/i/o/pbbyfcys/1826859421/5164ba3526f824387d4e7f452d58/claude+connected+message.png?expires=1781782200&signature=f2185bc9ff85df0f91afb09d0d6d4c286ea628a3e8193453c6fad5e65aaea46c&req=dSglEMF7lIVdWPMW1HO4zRcNri8Jdie7OalSMsyVvcCE2e5jrgLu3v9d59OR%0AlsP6%0A) **## Cursor** Configure MCP servers in a JSON file. 1. Open the file from **MCP** under **Cursor Settings**, then select **Add new server**. ​ 2. Copy and paste the JSON configuration shown above. For detailed steps, go to the [Cursor website](https://cursor.com/) and locate the section [Using ‘mcp.json’](https://cursor.com/docs/context/mcp#using-mcpjson) in the article [Model Context Protocol (MCP)](https://cursor.com/docs/context/mcp). **## VS code** For detailed steps, go to the Visual Studio website and see the article [Use MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers). **## Other clients** Most MCP clients do not yet support the latest MCP specification. To connect to the Foundational MCP server, use a bridge client such as `npx mcp-remote`. We recommend this approach and use it in the examples below. When you use `npx mcp-remote` or another bridge client, make sure it runs on the fixed port `8818`: ``` { "mcpServers": { "foundational-io": { "command": "npx", "args": ["mcp-remote", "https://mcp.foundational.io", "8818"] } } } ``` **Install Node.js and the `mcp-remote` package** To use a remote MCP server, install both **Node.js** and the **`mcp-remote`** package. If Node.js is not already installed, go to [nodejs.org](https://nodejs.org/) and download the **LTS (Long-Term Support)** version for your operating system. **Could not display content** After installing Node.js, open your terminal or command prompt and install the `mcp-remote` package globally: ``` npm install -g mcp-remote ``` --- # Machine-to-machine authentication Use machine-to-machine authentication for automated systems, CI/CD pipelines, or server-to-server integrations where interactive OAuth flows are not practical. This method lets you embed Foundational MCP capabilities into backend services, automated workflows, or custom AI deployments without requiring user interaction. ## When to use machine-to-machine authentication - Deploy MCP servers in production environments ​ - Integrate Foundational into automated data pipelines ​ - Build custom AI tools that need programmatic access ​ - Run server-side applications that cannot use OAuth flows ## Configure machine-to-machine authentication 1. Generate API keys. Follow the instructions in the article [Create API Tokens](https://docs.foundational.io/en/articles/9920307-create-api-tokens). ​ 2. Configure the MCP server. Add the bearer token in the format `CLIENT_ID:SECRET_KEY`. ​ ``` { "mcpServers": { "foundational-io": { "type": "streamable-http", "url": "https://mcp.foundational.io/mcp", "headers": { "Authorization": "Bearer CLIENT_ID:SECRET_KEY" } } } } ``` **IMPORTANT:** For desktop applications such as Claude Desktop, Claude Code, or Cursor, continue to use the regular OAuth authentication flow. Machine-to-machine authentication is designed only for headless, automated, or server-side deployments. --- # Troubleshooting MCP Server Errors If the MCP server fails to load, you’ll see an error in the UI or logs. ![MCP Server Error](https://downloads.intercomcdn.com/i/o/pbbyfcys/1826834514/471ce7dcedef5c875e4e56fcda95/claude-mcp-error.png?expires=1781782200&signature=265ba2db8f5bf8bbd6e581a66c83b3f37913fbbbada96e74b3ababc20efcb87e&req=dSglEMF9mYReXfMW1HO4zaXToocght82AyEw%2FcskygaaO6oP60nkAf7Vjch2%0AAHpUCejZRtDdhEOt%2BYs%3D%0A) Open the logs to check details. For **Claude on macOS** logs go to: /Users//Library/Logs/Claude/mcp-server-foundational-io.log The sections below describe common errors and how to fix them. **## TransformStream Error** **Problem** The MCP server fails to start. The logs show an error such as: ​ ``` ReferenceError: TransformStream is not defined ``` or a Node.js version warning: ``` npm WARN cli npm v10.9.2 does not support Node.js v16.18.1. This version of npm supports the following node versions: ^18.17.0 || >=20.5.0. ``` **Cause** An outdated Node.js version is installed. The Foundational MCP server requires Node.js **v22 or later** to run correctly. **Fix** 1. List all installed Node.js versions: ​ ``` nvm list ``` 2. Uninstall versions earlier than v22. For example: ​ ``` nvm uninstall v16.18.1 ``` 3. Install or switch to Node.js v22 or later. 4. After updating Node.js, restart your AI tool or terminal session. **## NPX Cache Issues** **Problem** The MCP server fails to load or connect. You may see one of these errors: - `command not found: mcp-remote` - `Error: Cannot find module 'mcp-remote'` - `ENOENT: no such file or directory` **Cause** NPX caches packages globally to improve performance. If the `mcp-remote` package updates or the cache becomes corrupted, NPX may use an outdated or broken version instead of fetching the latest one. **Fix** 1. Clear the NPX cache: ​ ``` npx clear-npx-cache ``` 2. Reinstall the `mcp-remote` package: ``` npm install -g mcp-remote ``` 3. Restart your AI tool (Claude Desktop, Cursor, VS Code, etc.). The MCP server should now load correctly. **## NPM Package Download SSL Errors** **Problem** You see SSL errors when running `npx mcp-remote` or `npm install -g mcp-remote`, such as: - `unable to get local issuer certificate` - `self signed certificate in certificate chain` - Package installation fails with SSL/TLS errors **Cause** Corporate proxies or firewalls can intercept HTTPS connections to the npm registry (`registry.npmjs.org`). This causes npm to fail SSL certificate verification when downloading packages, preventing `npx` from fetching the `mcp-remote` package needed to run the MCP server. **Fix** **IMPORTANT:** This disables SSL verification only for npm package downloads. For a secure setup, ask your IT team to configure npm to use your corporate CA certificate or proxy settings. 1. Temporarily disable SSL verification: ​ ``` npm config set strict-ssl false ``` 2. Reinstall or run the package: ``` npm install -g mcp-remote ``` 3. Re-enable SSL verification after installation: ​ ``` npm config set strict-ssl tru ```